{ "openapi": "3.1.0", "info": { "title": "Sodot Crypto Vault API", "description": "Crypto Vault OpenApi Spec", "version": "0.1.0" }, "paths": { "/health": { "get": { "tags": [ "Common" ], "summary": "Health check", "operationId": "health-check" } }, "/openapi.json": { "get": { "tags": [ "Docs" ], "summary": "OpenAPI specification (JSON)", "operationId": "openapi-json", "responses": { "200": { "description": "OpenAPI specification of this API, serialized as JSON.", "content": { "application/json": {} } } } } }, "/openapi.yaml": { "get": { "tags": [ "Docs" ], "summary": "OpenAPI specification (YAML)", "operationId": "openapi-yaml", "responses": { "200": { "description": "OpenAPI specification of this API, serialized as YAML.", "content": { "application/yaml": {} } } } } }, "/v1/info": { "get": { "tags": [ "Common" ], "summary": "Info", "operationId": "info", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Info" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/system-info": { "get": { "tags": [ "Common" ], "summary": "System Info", "operationId": "system-info", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemInfo" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/users": { "get": { "tags": [ "Users" ], "summary": "List users", "operationId": "list-users", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "display_name_like", "description": "Non-case sensitive filter", "schema": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "email_contains", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "is_in_groups", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "is_type", "schema": { "anyOf": [ { "$ref": "#/components/schemas/UserTypeFilter" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "style": "form" }, { "in": "query", "name": "user_ids", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "A page of results returned by a paginated query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "post": { "tags": [ "Users" ], "summary": "Create a new user", "operationId": "create-user", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "CreateUserResponse", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "user_groups": { "type": "array", "items": { "$ref": "#/$defs/UserGroup" } } }, "oneOf": [ { "type": "object", "properties": { "cloud_provider": { "$ref": "#/$defs/CloudProvider" }, "email": { "type": "string" }, "type": { "type": "string", "const": "human" } }, "required": [ "type", "email", "cloud_provider" ] }, { "type": "object", "properties": { "api_key": { "type": "string" }, "type": { "type": "string", "const": "machine" } }, "required": [ "type", "api_key" ] } ], "required": [ "id", "display_name", "user_groups", "created_at", "created_by", "last_updated_at", "last_updated_by" ], "$defs": { "CloudProvider": { "type": "string", "enum": [ "azure", "gcp" ] }, "UserGroup": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "display_name" ] } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "tags": [ "Users" ], "summary": "Delete multiple users", "operationId": "delete-users", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "user_ids", "description": "Comma-separated list", "required": true, "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/users/{user_id}": { "get": { "tags": [ "Users" ], "summary": "Get a user by ID", "operationId": "get-user", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserFullInformation" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "put": { "tags": [ "Users" ], "summary": "Update a user", "operationId": "update-user", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/users/{user_id}/api-key": { "put": { "tags": [ "Users" ], "summary": "Rotate a machine user's API key", "operationId": "rotate-api-key", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ApiKeyResponse", "type": "object", "properties": { "api_key": { "type": "string" } }, "required": [ "api_key" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/users/{user_id}/passkeys": { "get": { "tags": [ "Auth" ], "summary": "List a user's enrolled passkeys", "operationId": "list-passkeys", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "Response for `GET /v1/users/{user_id}/passkeys`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPasskeysResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "put": { "tags": [ "Auth" ], "summary": "Admin: remove all passkeys and reset to TOFU state", "operationId": "reset-passkeys", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "post": { "tags": [ "Auth" ], "summary": "Enroll a new passkey (WebAuthn registration)", "operationId": "enroll-passkey", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.\n\nThis route should omit the header on the bootstrap enroll-passkey request (the user's first passkey), where the client has no existing credential to sign with. Every other enroll-passkey caller (proof-of-possession from an already-enrolled credential) MUST send it.", "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "description": "Body for `POST /v1/users/{user_id}/passkeys`.\nUsed for first-enrollment (TOFU) and add-passkey (with existing-passkey proof).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollPasskeyRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "tags": [ "Auth" ], "summary": "Remove an enrolled passkey", "operationId": "remove-passkey", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "description": "Body for `DELETE /v1/users/{user_id}/passkeys` (signed request).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovePasskeyRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/keys": { "get": { "tags": [ "Keys" ], "summary": "List keys", "operationId": "list-keys", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "display_name_like", "description": "Non-case sensitive filter", "schema": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "environments", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "is_frozen", "schema": { "type": [ "boolean", "null" ] }, "style": "form" }, { "in": "query", "name": "key_ids", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "style": "form" }, { "in": "query", "name": "venue_ids", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "A page of results returned by a paginated query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page2" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "post": { "tags": [ "Keys" ], "summary": "Create a new key", "operationId": "create-key", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKeyRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "KeyFullInformation", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "display_name": { "type": "string" }, "environment": { "type": "string" }, "freeze_reason": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_frozen": { "type": "boolean" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "latest_version": { "type": "integer", "format": "uint16", "default": 0, "maximum": 65535, "minimum": 0 }, "metadata": { "type": [ "string", "null" ] }, "scheme": { "$ref": "#/$defs/KeyScheme" }, "security_groups": { "type": "array", "items": { "$ref": "#/$defs/SecurityGroup" } }, "venue_id": { "type": "string" }, "versions": { "type": "array", "default": [], "items": { "$ref": "#/$defs/KeyVersionInfo" } } }, "required": [ "id", "display_name", "scheme", "venue_id", "environment", "is_frozen", "security_groups", "created_at", "created_by", "last_updated_at", "last_updated_by" ], "$defs": { "KeyDescriptor": { "oneOf": [ { "type": "object", "properties": { "public_key": { "type": "string" }, "scheme": { "type": "string", "const": "Ed25519" } }, "required": [ "scheme", "public_key" ] }, { "type": "object", "properties": { "public_key": { "type": "string" }, "scheme": { "type": "string", "const": "Rsa4096" } }, "required": [ "scheme", "public_key" ] } ] }, "KeyExpirationDate": { "description": "The expiration date can be one of: unset, never, or a date in the format YYYY-MM-DD", "type": "string" }, "KeyScheme": { "type": "string", "enum": [ "ed25519", "hmac-sha256", "hmac-sha384", "hmac-sha512", "rs256" ] }, "KeyVersionInfo": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "expiration_date": { "$ref": "#/$defs/KeyExpirationDate" }, "key_descriptor": { "anyOf": [ { "$ref": "#/$defs/KeyDescriptor" }, { "type": "null" } ] }, "venue_api_key": { "type": [ "string", "null" ] }, "version": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 0 } }, "required": [ "version", "created_at", "created_by", "expiration_date" ] }, "SecurityGroup": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "signing_policy_id": { "type": "string" } }, "required": [ "id", "display_name", "signing_policy_id" ] } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "tags": [ "Keys" ], "summary": "Delete multiple keys", "operationId": "delete-keys", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteKeysBody" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/keys/{key_id}/versions": { "post": { "tags": [ "Keys" ], "summary": "Create a new key version", "operationId": "create-key-version", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateKeyRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/keys/{key_id}/sign": { "post": { "tags": [ "Keys" ], "summary": "Sign a message with a key", "operationId": "sign-key", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/keys/{key_id}": { "get": { "tags": [ "Keys" ], "summary": "Get a key by ID", "operationId": "get-key", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyFullInformation" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "patch": { "tags": [ "Keys" ], "summary": "Update a key", "operationId": "update-key", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "description": "Partial update (PATCH) request for a key.\n\nUses merge-patch semantics: only fields present in the request body are\nupdated; omitted fields are left unchanged.\n\n- `display_name`: set to update the key's display name; omit keeping the current value.\n- `environment`: set to update the key's environment; omit keeping the current value.\n- `metadata`: omit leaving unchanged, set to a string to update, set to `null` to clear.\n- `versions`: list of per-version updates to apply. An empty list (or omitted) means\n no version-level changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKeyRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/keys/freeze": { "post": { "tags": [ "Keys" ], "summary": "Freeze keys", "operationId": "freeze-keys", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "key_ids", "description": "Comma-separated list of key IDs to freeze/unfreeze", "schema": { "description": "Comma-separated list of key IDs to freeze/unfreeze", "type": "string" }, "style": "form" }, { "in": "query", "name": "venue_id", "description": "Venue whose keys to freeze/unfreeze", "schema": { "description": "Venue whose keys to freeze/unfreeze", "type": [ "string", "null" ] }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreezeBody" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Array_of_string", "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/keys/unfreeze": { "post": { "tags": [ "Keys" ], "summary": "Unfreeze keys", "operationId": "unfreeze-keys", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "key_ids", "description": "Comma-separated list of key IDs to freeze/unfreeze", "schema": { "description": "Comma-separated list of key IDs to freeze/unfreeze", "type": "string" }, "style": "form" }, { "in": "query", "name": "venue_id", "description": "Venue whose keys to freeze/unfreeze", "schema": { "description": "Venue whose keys to freeze/unfreeze", "type": [ "string", "null" ] }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Array_of_string", "type": "array", "items": { "type": "string" } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/requests/{request_id}": { "get": { "tags": [ "Requests" ], "summary": "Get request status", "operationId": "get-request-status", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed (success or failure)", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "CompletedResult", "oneOf": [ { "type": "object", "properties": { "data": { "$ref": "#/$defs/CreateUserResponse" }, "type": { "type": "string", "const": "user" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "data": { "$ref": "#/$defs/KeyFullInformation" }, "type": { "type": "string", "const": "key" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "data": { "$ref": "#/$defs/UserGroupFullInformation" }, "type": { "type": "string", "const": "user_group" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "data": { "$ref": "#/$defs/SecurityGroupFullInformation" }, "type": { "type": "string", "const": "security_group" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "data": { "$ref": "#/$defs/VenueResponse" }, "type": { "type": "string", "const": "venue" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "const": "affected_key_ids" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "data": { "$ref": "#/$defs/ApiKeyResponse" }, "type": { "type": "string", "const": "api_key" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "data": { "$ref": "#/$defs/GetAdminPoliciesResponse" }, "type": { "type": "string", "const": "admin_policies" } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "empty" } }, "required": [ "type" ] } ], "$defs": { "Action": { "description": "The action to take when a rule matches or as a default.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "approve" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "deny" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "external_approval" } }, "$ref": "#/$defs/ExternalApproval", "required": [ "type" ] } ] }, "AdminConditions": { "description": "Rule conditions for an admin policy rule.", "type": "object", "properties": { "signing_policies": { "$ref": "#/$defs/SigningPolicyScope" }, "user_in_groups": { "$ref": "#/$defs/UserInGroups" } }, "required": [ "user_in_groups", "signing_policies" ] }, "AdminPolicyResponse": { "type": "object", "properties": { "default_action": { "$ref": "#/$defs/Action" }, "policy": { "$ref": "#/$defs/AdminPolicyType" }, "rules": { "type": "array", "items": { "$ref": "#/$defs/AdminRule" } }, "version_number": { "type": "integer", "format": "uint32", "minimum": 0 } }, "required": [ "policy", "rules", "default_action", "version_number" ] }, "AdminPolicyType": { "description": "The type of administrative action a policy applies to.", "oneOf": [ { "type": "string", "enum": [ "manage_users", "manage_user_groups", "modify_admin_policy", "manage_signing_policies_and_security_groups", "view_system_resources", "manage_address_book", "configure_venues", "import_generate_manage_keys_and_wallets", "access_keys_backup", "view_export_audit_log", "manage_vaults" ] }, { "description": "Freeze keys, wallets, and entire vaults. Not per-vault scoped.", "type": "string", "const": "freeze_assets" }, { "description": "Unfreeze keys, wallets, and entire vaults. Not per-vault scoped.", "type": "string", "const": "unfreeze_assets" } ] }, "AdminRule": { "description": "A single rule in an admin policy.", "type": "object", "properties": { "action": { "$ref": "#/$defs/Action" }, "conditions": { "$ref": "#/$defs/AdminConditions" }, "rule_index": { "type": "integer", "format": "uint32", "minimum": 1 } }, "required": [ "rule_index", "conditions", "action" ] }, "AnyUser": { "type": "string", "enum": [ "AnyUser" ] }, "ApiKeyResponse": { "type": "object", "properties": { "api_key": { "type": "string" } }, "required": [ "api_key" ] }, "CloudProvider": { "type": "string", "enum": [ "azure", "gcp" ] }, "CreateUserResponse": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "user_groups": { "type": "array", "items": { "$ref": "#/$defs/UserGroup" } } }, "oneOf": [ { "type": "object", "properties": { "cloud_provider": { "$ref": "#/$defs/CloudProvider" }, "email": { "type": "string" }, "type": { "type": "string", "const": "human" } }, "required": [ "type", "email", "cloud_provider" ] }, { "type": "object", "properties": { "api_key": { "type": "string" }, "type": { "type": "string", "const": "machine" } }, "required": [ "type", "api_key" ] } ], "required": [ "id", "display_name", "user_groups", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "ExternalApproval": { "description": "An approval action requiring external approval from a user group.", "type": "object", "properties": { "threshold": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 1 }, "user_group_id": { "type": "string" } }, "required": [ "user_group_id", "threshold" ] }, "GetAdminPoliciesResponse": { "description": "A set of admin policies.", "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/$defs/AdminPolicyResponse" } } }, "required": [ "policies" ] }, "ImportDecoding": { "type": "string", "enum": [ "raw", "base64", "rfc8032" ] }, "Key": { "type": "object", "properties": { "display_name": { "type": "string" }, "environment": { "type": "string" }, "freeze_reason": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_frozen": { "type": "boolean" }, "latest_version": { "type": "integer", "format": "uint16", "default": 0, "maximum": 65535, "minimum": 0 }, "scheme": { "$ref": "#/$defs/KeyScheme" }, "venue_id": { "type": "string" } }, "required": [ "id", "display_name", "scheme", "venue_id", "environment", "is_frozen" ] }, "KeyDescriptor": { "oneOf": [ { "type": "object", "properties": { "public_key": { "type": "string" }, "scheme": { "type": "string", "const": "Ed25519" } }, "required": [ "scheme", "public_key" ] }, { "type": "object", "properties": { "public_key": { "type": "string" }, "scheme": { "type": "string", "const": "Rsa4096" } }, "required": [ "scheme", "public_key" ] } ] }, "KeyExpirationDate": { "description": "The expiration date can be one of: unset, never, or a date in the format YYYY-MM-DD", "type": "string" }, "KeyFullInformation": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "display_name": { "type": "string" }, "environment": { "type": "string" }, "freeze_reason": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_frozen": { "type": "boolean" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "latest_version": { "type": "integer", "format": "uint16", "default": 0, "maximum": 65535, "minimum": 0 }, "metadata": { "type": [ "string", "null" ] }, "scheme": { "$ref": "#/$defs/KeyScheme" }, "security_groups": { "type": "array", "items": { "$ref": "#/$defs/SecurityGroup" } }, "venue_id": { "type": "string" }, "versions": { "type": "array", "default": [], "items": { "$ref": "#/$defs/KeyVersionInfo" } } }, "required": [ "id", "display_name", "scheme", "venue_id", "environment", "is_frozen", "security_groups", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "KeyScheme": { "type": "string", "enum": [ "ed25519", "hmac-sha256", "hmac-sha384", "hmac-sha512", "rs256" ] }, "KeyVersionInfo": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "expiration_date": { "$ref": "#/$defs/KeyExpirationDate" }, "key_descriptor": { "anyOf": [ { "$ref": "#/$defs/KeyDescriptor" }, { "type": "null" } ] }, "venue_api_key": { "type": [ "string", "null" ] }, "version": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 0 } }, "required": [ "version", "created_at", "created_by", "expiration_date" ] }, "NetworkFamily": { "description": "Network family a wallet belongs to. Selects both the BIP-44 coin type used\nwhen deriving the wallet's address and the signing curve.", "type": "string", "enum": [ "evm", "solana" ] }, "PublicKeyEncoding": { "type": "string", "enum": [ "pem", "csr" ] }, "SecurityGroup": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "signing_policy_id": { "type": "string" } }, "required": [ "id", "display_name", "signing_policy_id" ] }, "SecurityGroupFullInformation": { "description": "A security group's members, tagged by kind in `member_type`. A group is homogeneous: an\noff-chain group reports `Keys`, a vault group reports `Wallets` (including\nthe empty case, where the kind comes from the signing policy).", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "signing_policy_id": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "member_type": { "type": "string", "const": "keys" }, "members": { "type": "array", "items": { "$ref": "#/$defs/Key" } } }, "required": [ "member_type", "members" ] }, { "type": "object", "properties": { "member_type": { "type": "string", "const": "wallets" }, "members": { "type": "array", "items": { "$ref": "#/$defs/Wallet" } } }, "required": [ "member_type", "members" ] } ], "required": [ "id", "display_name", "signing_policy_id", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "SigningPolicyScope": { "description": "The set of signing policies an admin rule applies to.\n\nMirrors `policy_engine::SigningPolicyScope`, kept as a separate copy so\n`external-api-types` does not depend on `policy-engine`.", "oneOf": [ { "description": "Applies to any signing policy.", "type": "string", "const": "Any" }, { "description": "Applies only to the listed signing policies (an empty list never matches).", "type": "object", "properties": { "Only": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "Only" ] } ] }, "UserGroup": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "display_name" ] }, "UserGroupFullInformation": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/$defs/UserInfo" } } }, "required": [ "id", "display_name", "members", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "UserInGroups": { "description": "Which users a rule applies to: either any authenticated user or members of specific groups.", "anyOf": [ { "description": "Any authenticated user.", "$ref": "#/$defs/AnyUser" }, { "description": "Users belonging to one of the listed groups.", "type": "array", "items": { "type": "string" } } ] }, "UserInfo": { "type": "object", "properties": { "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "display_name" ] }, "VenueResponse": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "display_name": { "type": "string" }, "id": { "type": "string" }, "is_seeded": { "type": "boolean" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha256" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha384" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha512" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "public_key_encoding": { "$ref": "#/$defs/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "ed25519" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "public_key_encoding": { "$ref": "#/$defs/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "rs256" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] } ], "required": [ "id", "display_name", "is_seeded", "created_by", "created_at", "last_updated_by", "last_updated_at" ] }, "Wallet": { "type": "object", "properties": { "address": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "network_family": { "$ref": "#/$defs/NetworkFamily" } }, "required": [ "address", "display_name", "network_family" ] } } } }, "application/json; variant=failed": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "FailedResult", "type": "object", "properties": { "err_msg": { "description": "The error message, same as the `err_msg` field in the standard error", "type": "string" }, "err_type": { "description": "The error type, same as the `err_type` field in the standard error", "type": "string" }, "failure_code": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 0 } }, "required": [ "failure_code", "err_type", "err_msg" ] } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/user-groups": { "get": { "tags": [ "UserGroups" ], "summary": "List user groups", "operationId": "list-user-groups", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "display_name_like", "description": "Non-case sensitive filter", "schema": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "style": "form" }, { "in": "query", "name": "members", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "A page of results returned by a paginated query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page3" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "post": { "tags": [ "UserGroups" ], "summary": "Create a new user group", "operationId": "create-user-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserGroupRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "UserGroupFullInformation", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/$defs/UserInfo" } } }, "required": [ "id", "display_name", "members", "created_at", "created_by", "last_updated_at", "last_updated_by" ], "$defs": { "UserInfo": { "type": "object", "properties": { "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "display_name" ] } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "tags": [ "UserGroups" ], "summary": "Delete multiple user groups", "operationId": "delete-user-groups", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "user_group_ids", "description": "Comma-separated list", "required": true, "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/user-groups/{group_id}/members/{user_id}": { "put": { "tags": [ "UserGroups" ], "summary": "Add a user to a user group", "operationId": "add-user-to-user-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/user-groups/{group_id}": { "put": { "tags": [ "UserGroups" ], "summary": "Updates the user group, replace all mutable fields and replaces all users of the group with the new users.", "operationId": "update-user-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "description": "This request is used to update the state of a user group.\nIt will replace the display_name, description, and the list of members with the given values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserGroupRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/user-groups/{group_id}/members": { "delete": { "tags": [ "UserGroups" ], "summary": "Remove users from a user group", "operationId": "remove-users-from-user-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "user_ids", "description": "Comma-separated list", "required": true, "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "patch": { "tags": [ "UserGroups" ], "summary": "Add multiple users to a user group", "operationId": "add-users-to-user-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserGroupMembersRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/security-groups": { "get": { "tags": [ "SecurityGroups" ], "summary": "List security groups", "operationId": "list-security-groups", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "display_name_like", "description": "Non-case sensitive filter", "schema": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "style": "form" }, { "in": "query", "name": "members", "description": "Comma-separated member names/addresses (keys or wallets per the group's\nsigning policy); restricts the listing to groups containing at least one.", "schema": { "description": "Comma-separated member names/addresses (keys or wallets per the group's\nsigning policy); restricts the listing to groups containing at least one.", "type": "string" }, "style": "form" }, { "in": "query", "name": "signing_policy_id", "description": "Signing policy that scopes the listing: either the literal `offchain` (the off-chain key-group namespace) or a vault's signing policy, a free-form name equal to the vault's name.", "required": true, "schema": { "description": "Signing policy that scopes the listing: either the literal `offchain` (the off-chain key-group namespace) or a vault's signing policy, a free-form name equal to the vault's name.", "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "A page of results returned by a paginated query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page4" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "post": { "tags": [ "SecurityGroups" ], "summary": "Create a new security group", "operationId": "create-security-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecurityGroupRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "SecurityGroupFullInformation", "description": "A security group's members, tagged by kind in `member_type`. A group is homogeneous: an\noff-chain group reports `Keys`, a vault group reports `Wallets` (including\nthe empty case, where the kind comes from the signing policy).", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "signing_policy_id": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "member_type": { "type": "string", "const": "keys" }, "members": { "type": "array", "items": { "$ref": "#/$defs/Key" } } }, "required": [ "member_type", "members" ] }, { "type": "object", "properties": { "member_type": { "type": "string", "const": "wallets" }, "members": { "type": "array", "items": { "$ref": "#/$defs/Wallet" } } }, "required": [ "member_type", "members" ] } ], "required": [ "id", "display_name", "signing_policy_id", "created_at", "created_by", "last_updated_at", "last_updated_by" ], "$defs": { "Key": { "type": "object", "properties": { "display_name": { "type": "string" }, "environment": { "type": "string" }, "freeze_reason": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_frozen": { "type": "boolean" }, "latest_version": { "type": "integer", "format": "uint16", "default": 0, "maximum": 65535, "minimum": 0 }, "scheme": { "$ref": "#/$defs/KeyScheme" }, "venue_id": { "type": "string" } }, "required": [ "id", "display_name", "scheme", "venue_id", "environment", "is_frozen" ] }, "KeyScheme": { "type": "string", "enum": [ "ed25519", "hmac-sha256", "hmac-sha384", "hmac-sha512", "rs256" ] }, "NetworkFamily": { "description": "Network family a wallet belongs to. Selects both the BIP-44 coin type used\nwhen deriving the wallet's address and the signing curve.", "type": "string", "enum": [ "evm", "solana" ] }, "Wallet": { "type": "object", "properties": { "address": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "network_family": { "$ref": "#/$defs/NetworkFamily" } }, "required": [ "address", "display_name", "network_family" ] } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "tags": [ "SecurityGroups" ], "summary": "Delete multiple security groups", "operationId": "delete-security-groups", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "security_group_ids", "description": "Comma-separated list", "required": true, "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/security-groups/{group_id}/members/{member_id}": { "put": { "tags": [ "SecurityGroups" ], "summary": "Add a member to a security group", "operationId": "add-member-to-security-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/security-groups/{group_id}": { "put": { "tags": [ "SecurityGroups" ], "summary": "Updates the security group, replace all mutable fields and replaces all members of the group with the new members.", "operationId": "update-security-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSecurityGroupRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/security-groups/{group_id}/members": { "delete": { "tags": [ "SecurityGroups" ], "summary": "Remove members from a security group", "operationId": "remove-members-from-security-group", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "members", "description": "Comma-separated member names/addresses to remove. Interpreted as keys or\nwallets according to the group's signing policy.", "required": true, "schema": { "description": "Comma-separated member names/addresses to remove. Interpreted as keys or\nwallets according to the group's signing policy.", "type": "string" }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "patch": { "tags": [ "SecurityGroups" ], "summary": "Add members to a security group", "operationId": "add-security-group-members", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSecurityGroupMembersRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/admin-policies": { "get": { "tags": [ "AdminPolicies" ], "summary": "Get admin policies", "operationId": "get-admin-policies", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "A set of admin policies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAdminPoliciesResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "put": { "tags": [ "AdminPolicies" ], "summary": "Update admin policies", "operationId": "put-admin-policies", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPolicySetRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "null", "type": "null" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/signing-policies": { "get": { "tags": [ "SigningPolicies" ], "summary": "List signing policies", "operationId": "list-signing-policies", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "A set of signing policies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSigningPoliciesResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/signing-policies/{policy_id}": { "get": { "tags": [ "SigningPolicies" ], "summary": "Get a signing policy", "operationId": "get-signing-policy", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "A single signing policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningPolicyResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "put": { "tags": [ "SigningPolicies" ], "summary": "Replace a signing policy", "operationId": "put-signing-policy", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningPolicySetRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "null", "type": "null" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/audit-logs": { "get": { "tags": [ "AuditLogs" ], "summary": "List audit logs (JSON or CSV)", "operationId": "list-audit-logs", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "cursor", "schema": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0 }, "style": "form" }, { "in": "query", "name": "end_time", "schema": { "type": [ "string", "null" ], "format": "date-time" }, "style": "form" }, { "in": "query", "name": "event_types", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "format", "description": "Response format: `json` (default, paginated) or `csv` (all matching rows).", "schema": { "description": "Response format: `json` (default, paginated) or `csv` (all matching rows).", "$ref": "#/components/schemas/AuditLogFormat", "default": "json" }, "style": "form" }, { "in": "query", "name": "key_ids", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "style": "form" }, { "in": "query", "name": "performed_by", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "start_time", "schema": { "type": [ "string", "null" ], "format": "date-time" }, "style": "form" }, { "in": "query", "name": "status", "schema": { "anyOf": [ { "$ref": "#/components/schemas/AuditLogStatus" }, { "type": "null" } ] }, "style": "form" }, { "in": "query", "name": "topic", "schema": { "anyOf": [ { "$ref": "#/components/schemas/AuditLogTopic" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "description": "Audit logs in the requested format (JSON or CSV). CSV columns: seq, request_id, event_type, topic, status, failure_reason, performed_by, key_id, vault_id, wallet_address, logged_at, completed_at.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Page", "description": "A page of results returned by a paginated query.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/AuditLogEntry" } }, "next_cursor": { "description": "Cursor pointing past the last item in this page.\n`None` means there are no more results.", "type": [ "integer", "null" ], "format": "uint64", "minimum": 0 }, "total": { "description": "Total number of items matching the filter (across all pages).", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "items", "total" ], "$defs": { "AuditEventMetadata": { "type": "object", "properties": { "key_id": { "type": [ "string", "null" ] }, "vault_id": { "type": [ "string", "null" ] }, "wallet_address": { "type": [ "string", "null" ] } } }, "AuditEventType": { "type": "string", "enum": [ "user_created", "user_updated", "users_deleted", "api_key_rotated", "passkey_added", "passkey_removed", "passkey_reset", "user_group_created", "user_group_updated", "user_groups_deleted", "user_added_to_user_group", "user_removed_from_user_group", "security_group_created", "security_group_updated", "security_groups_deleted", "keys_added_to_security_group", "keys_removed_from_security_group", "admin_policies_updated", "key_created", "key_imported", "key_updated", "keys_deleted", "key_version_added", "key_frozen", "key_unfrozen", "keys_backup_created", "sign_request_completed", "sign_request_failed", "sign_request_blocked_by_freeze", "sign_request_blocked_by_policy", "request_denied", "admin_policy_created", "admin_policy_updated", "admin_policy_deleted", "signing_policy_updated", "module_policy_created", "module_policy_updated", "module_policy_deleted", "recovery_kit_exported", "failed_auth_attempt", "venue_created", "venue_updated", "venues_deleted", "vault_created", "vault_updated", "vaults_frozen", "vaults_unfrozen", "wallet_generated", "wallet_updated", "wallets_deleted", "wallets_frozen", "wallets_unfrozen" ] }, "AuditLogEntry": { "type": "object", "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "event_type": { "$ref": "#/$defs/AuditEventType" }, "failure_reason": { "type": [ "string", "null" ] }, "logged_at": { "type": "string", "format": "date-time" }, "metadata": { "$ref": "#/$defs/AuditEventMetadata" }, "performed_by": { "description": "`None` for failed authentication attempts where user identity is unknown.", "type": [ "string", "null" ] }, "raw_request": true, "request_id": { "type": [ "string", "null" ] }, "seq": { "type": "integer", "format": "uint64", "minimum": 0 }, "status": { "$ref": "#/$defs/AuditLogStatus" }, "topic": { "$ref": "#/$defs/AuditLogTopic" } }, "required": [ "seq", "event_type", "topic", "status", "raw_request", "metadata", "logged_at" ] }, "AuditLogStatus": { "type": "string", "enum": [ "pending", "success", "failure" ] }, "AuditLogTopic": { "type": "string", "enum": [ "admin", "signing" ] } } } }, "text/csv": {} } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/venues": { "get": { "tags": [ "Venues" ], "summary": "List all venues", "operationId": "list-venues", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "display_name_like", "description": "Non-case sensitive filter", "schema": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "import_decodings", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "is_seeded", "schema": { "type": [ "boolean", "null" ] }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "style": "form" }, { "in": "query", "name": "signing_schemes", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "query", "name": "venue_ids", "description": "Comma-separated list", "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "A page of results returned by a paginated query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page5" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "post": { "tags": [ "Venues" ], "summary": "Create a new venue", "operationId": "create-venue", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVenueRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "VenueResponse", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "display_name": { "type": "string" }, "id": { "type": "string" }, "is_seeded": { "type": "boolean" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha256" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha384" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha512" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "public_key_encoding": { "$ref": "#/$defs/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "ed25519" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "public_key_encoding": { "$ref": "#/$defs/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "rs256" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] } ], "required": [ "id", "display_name", "is_seeded", "created_by", "created_at", "last_updated_by", "last_updated_at" ], "$defs": { "ImportDecoding": { "type": "string", "enum": [ "raw", "base64", "rfc8032" ] }, "PublicKeyEncoding": { "type": "string", "enum": [ "pem", "csr" ] } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } }, "delete": { "tags": [ "Venues" ], "summary": "Delete multiple venues", "operationId": "delete-venues", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "query", "name": "venue_ids", "description": "Comma-separated list", "required": true, "schema": { "description": "Comma-separated list", "type": "string" }, "style": "form" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "AnyValue" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/venues/{venue_id}": { "get": { "tags": [ "Venues" ], "summary": "Get venue details", "operationId": "get-venue", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VenueResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } }, "put": { "tags": [ "Venues" ], "summary": "Update a venue", "operationId": "update-venue", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVenueRequest" } } }, "required": true }, "responses": { "202": { "description": "Request is being processed asynchronously", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ProcessingStatus", "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/$defs/ProcessingStatusValue" } }, "required": [ "status", "request_id" ], "$defs": { "ProcessingStatusValue": { "type": "string", "enum": [ "processing" ] } } } } } }, "200": { "description": "Request completed successfully", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "VenueResponse", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "display_name": { "type": "string" }, "id": { "type": "string" }, "is_seeded": { "type": "boolean" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha256" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha384" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha512" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "public_key_encoding": { "$ref": "#/$defs/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "ed25519" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/$defs/ImportDecoding" }, "public_key_encoding": { "$ref": "#/$defs/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "rs256" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] } ], "required": [ "id", "display_name", "is_seeded", "created_by", "created_at", "last_updated_by", "last_updated_at" ], "$defs": { "ImportDecoding": { "type": "string", "enum": [ "raw", "base64", "rfc8032" ] }, "PublicKeyEncoding": { "type": "string", "enum": [ "pem", "csr" ] } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "415": { "description": "Expected request with `Content-Type: application/json`", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/v1/whoami": { "get": { "tags": [ "Whoami" ], "summary": "Get current user identity and capabilities", "operationId": "whoami", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoamiResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } }, "/v1/keys-backup": { "get": { "tags": [ "KeysBackup" ], "summary": "Creates a backup file with all encrypted keys (JSON inside a ZIP)", "operationId": "keys-backup", "parameters": [ { "in": "header", "name": "authorization", "description": "Authentication token. Either 'ApiKey ' or 'Bearer '", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "header", "name": "x-request-nonce", "description": "Fixed-width hex (16 chars) of 8 random bytes - single-use nonce for replay protection.", "required": true, "schema": { "type": "string", "example": "0102030405060708" }, "example": "0102030405060708", "style": "simple" }, { "in": "header", "name": "x-request-timestamp", "description": "Fixed-width hex (16 chars) of a u64 little-endian timestamp in milliseconds since the Unix epoch (e.g. `00f6cd6c00000000` = 1_700_000_000_000 ms). Must be within 5 minutes of the server clock.", "required": true, "schema": { "type": "string", "example": "00f6cd6c00000000" }, "example": "00f6cd6c00000000", "style": "simple" }, { "in": "header", "name": "x-request-assertion", "description": "Base64url-encoded (RFC 4648 §5, no padding) authentication assertion. Two shapes: (a) human users - UTF-8 JSON of a WebAuthn assertion response, which carries its own credential id, authenticator data, client data JSON, and signature (typically 200-500 bytes once base64url-encoded); (b) machine users - raw bytes of an Ed25519 signature over the SHA-256 transcript challenge for this request (always 64 bytes, 86 base64url chars). The transcript challenge is the SHA-256 digest of a binary structure beginning with a `0x01` version byte and then five 4-byte little-endian length-prefixed fields: (1) HTTP method (e.g. `POST`); (2) URI path (no normalisation, no host/scheme); (3) URI query string (empty if absent); (4) request body bytes (empty if absent); (5) the `Authorization` header value with its scheme prefix (`Bearer`/`ApiKey`) and trailing whitespace stripped. After those fields the structure ends with the 8-byte little-endian `x-request-timestamp` value and the 8 raw bytes of `x-request-nonce`. The resulting 32-byte SHA-256 digest is what gets signed.", "required": true, "schema": { "type": "string", "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79" }, "example": "3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-796tvu_erb6t3q2-79", "style": "simple" } ], "responses": { "200": { "description": "A ZIP archive containing backup.json with the encrypted key backup", "content": { "application/zip": {} } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "parse_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "forbidden" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "not_found", "resource_not_found" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "resource_conflict" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "invalid_inputs" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "internal_server_error" ] } }, "required": [ "err_type", "err_msg" ] } } } }, "504": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "err_msg": { "type": "string" }, "err_type": { "type": "string", "enum": [ "gateway_timeout" ] } }, "required": [ "err_type", "err_msg" ] } } } } } } } }, "components": { "schemas": { "Action": { "description": "The action to take when a rule matches or as a default.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "approve" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "deny" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "external_approval" } }, "allOf": [ { "$ref": "#/components/schemas/ExternalApproval" } ], "required": [ "type" ] } ] }, "AdminConditions": { "description": "Rule conditions for an admin policy rule.", "type": "object", "properties": { "signing_policies": { "$ref": "#/components/schemas/SigningPolicyScope" }, "user_in_groups": { "$ref": "#/components/schemas/UserInGroups" } }, "required": [ "user_in_groups", "signing_policies" ] }, "AdminPolicyInput": { "type": "object", "properties": { "default_action": { "description": "Policy default action. v0 only supports `deny` (fail-closed).", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "deny" } }, "required": [ "type" ] } ] }, "policy": { "$ref": "#/components/schemas/AdminPolicyType" }, "previous_version": { "description": "The `version_number` from the last seen `AdminPolicyResponse`", "type": "integer", "format": "uint32", "minimum": 0 }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/AdminRule" } } }, "required": [ "policy", "rules", "default_action", "previous_version" ] }, "AdminPolicyResponse": { "type": "object", "properties": { "default_action": { "$ref": "#/components/schemas/Action" }, "policy": { "$ref": "#/components/schemas/AdminPolicyType" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/AdminRule" } }, "version_number": { "type": "integer", "format": "uint32", "minimum": 0 } }, "required": [ "policy", "rules", "default_action", "version_number" ] }, "AdminPolicySetRequest": { "type": "object", "properties": { "new_policies": { "type": "array", "items": { "$ref": "#/components/schemas/AdminPolicyInput" } } }, "required": [ "new_policies" ] }, "AdminPolicyType": { "description": "The type of administrative action a policy applies to.", "oneOf": [ { "type": "string", "enum": [ "manage_users", "manage_user_groups", "modify_admin_policy", "manage_signing_policies_and_security_groups", "view_system_resources", "manage_address_book", "configure_venues", "import_generate_manage_keys_and_wallets", "access_keys_backup", "view_export_audit_log", "manage_vaults" ] }, { "description": "Freeze keys, wallets, and entire vaults. Not per-vault scoped.", "type": "string", "const": "freeze_assets" }, { "description": "Unfreeze keys, wallets, and entire vaults. Not per-vault scoped.", "type": "string", "const": "unfreeze_assets" } ] }, "AdminRule": { "description": "A single rule in an admin policy.", "type": "object", "properties": { "action": { "$ref": "#/components/schemas/Action" }, "conditions": { "$ref": "#/components/schemas/AdminConditions" }, "rule_index": { "type": "integer", "format": "uint32", "minimum": 1 } }, "required": [ "rule_index", "conditions", "action" ] }, "AnyUser": { "type": "string", "enum": [ "AnyUser" ] }, "AuditLogFormat": { "type": "string", "enum": [ "json", "csv" ] }, "AuditLogStatus": { "type": "string", "enum": [ "pending", "success", "failure" ] }, "AuditLogTopic": { "type": "string", "enum": [ "admin", "signing" ] }, "CapabilityStatus": { "type": "string", "enum": [ "allowed", "denied" ] }, "CloudProvider": { "type": "string", "enum": [ "azure", "gcp" ] }, "CreateKeyRequest": { "type": "object", "properties": { "display_name": { "type": "string" }, "encrypted_private_key": { "type": [ "string", "null" ] }, "environment": { "type": "string" }, "expiration_date": { "allOf": [ { "$ref": "#/components/schemas/KeyExpirationDate" } ], "default": "unset" }, "id": { "type": "string" }, "metadata": { "type": [ "string", "null" ] }, "scheme": { "$ref": "#/components/schemas/KeyScheme" }, "venue_api_key": { "type": [ "string", "null" ] }, "venue_id": { "type": "string" } }, "required": [ "id", "display_name", "scheme", "venue_id", "environment" ] }, "CreateSecurityGroupRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "members": { "description": "Initial member names/addresses. interpreted as keys or wallets per the\ngroup's signing policy.", "type": "array", "items": { "type": "string" } }, "signing_policy_id": { "type": "string" } }, "required": [ "id", "display_name", "signing_policy_id" ] }, "CreateUserGroupRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "display_name" ] }, "CreateUserRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "cloud_provider": { "$ref": "#/components/schemas/CloudProvider" }, "email": { "type": "string" }, "sub": { "type": [ "string", "null" ] }, "type": { "type": "string", "const": "human" } }, "required": [ "type", "email", "cloud_provider" ] }, { "type": "object", "properties": { "public_key": { "$ref": "#/components/schemas/Ed25519PublicKey" }, "type": { "type": "string", "const": "machine" } }, "required": [ "type", "public_key" ] } ], "required": [ "id", "display_name" ] }, "CreateVenueRequest": { "type": "object", "properties": { "display_name": { "type": "string" }, "id": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha256" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha384" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha512" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "public_key_encoding": { "$ref": "#/components/schemas/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "ed25519" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "public_key_encoding": { "$ref": "#/components/schemas/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "rs256" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] } ], "required": [ "id", "display_name" ] }, "Cursor": { "description": "Cursor for keyset-based pagination. The cursor should be treated as an opaque string,\nand no assumptions made on its meaning or the stability of its format.", "type": "string" }, "DeleteKeyBody": { "type": "object", "properties": { "key_id": { "type": "string" }, "versions": { "$ref": "#/components/schemas/DeleteKeyVersionsSelector" } }, "required": [ "key_id", "versions" ] }, "DeleteKeyVersionsSelector": { "oneOf": [ { "type": "string", "enum": [ "All" ] }, { "type": "object", "properties": { "Specific": { "type": "array", "items": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 0 } } }, "additionalProperties": false, "required": [ "Specific" ] } ] }, "DeleteKeysBody": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/DeleteKeyBody" } } }, "required": [ "keys" ] }, "DeleteSecurityGroupMembersFilterQuery": { "type": "object", "properties": { "members": { "description": "Comma-separated member names/addresses to remove. Interpreted as keys or\nwallets according to the group's signing policy.", "type": "string" } }, "required": [ "members" ] }, "DeleteSecurityGroupsFilterQuery": { "type": "object", "properties": { "security_group_ids": { "description": "Comma-separated list", "type": "string" } }, "required": [ "security_group_ids" ] }, "DeleteUserGroupMembersFilterQuery": { "type": "object", "properties": { "user_ids": { "description": "Comma-separated list", "type": "string" } }, "required": [ "user_ids" ] }, "DeleteUserGroupsFilterQuery": { "type": "object", "properties": { "user_group_ids": { "description": "Comma-separated list", "type": "string" } }, "required": [ "user_group_ids" ] }, "DeleteUsersFilterQuery": { "type": "object", "properties": { "user_ids": { "description": "Comma-separated list", "type": "string" } }, "required": [ "user_ids" ] }, "DeleteVenuesFilterQuery": { "type": "object", "properties": { "venue_ids": { "description": "Comma-separated list", "type": "string" } }, "required": [ "venue_ids" ] }, "Ed25519PublicKey": { "description": "PEM-encoded Ed25519 SubjectPublicKeyInfo (RFC 8410 / RFC 7468). Decodes to a 32-byte verifying key on the Ed25519 curve.", "type": "string", "examples": [ "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAiojj3XQJ8ZX9UtstPLpdcspnCb8dlBIb83SIAbQPb1w=\n-----END PUBLIC KEY-----\n" ] }, "EnrollPasskeyRequest": { "description": "Body for `POST /v1/users/{user_id}/passkeys`.\nUsed for first-enrollment (TOFU) and add-passkey (with existing-passkey proof).", "type": "object", "properties": { "assertion": { "description": "WebAuthn registration response — proves possession of the new\npasskey's private key. Carries everything the verifier needs:\nthe credential id (`id`), authenticator data + attestation\nstatement, and the `clientDataJSON` whose challenge is the\ntranscript challenge derived from this request **with an empty\nbody**. The new passkey cannot commit to its own credential id\n(which only exists *after* the WebAuthn ceremony), so its\ntranscript-body slot is the empty byte string — not the actual\nrequest body." }, "device_name": { "type": "string" } }, "required": [ "device_name", "assertion" ] }, "Es256PublicKey": { "description": "PEM-encoded P-256 SubjectPublicKeyInfo (RFC 5480 / RFC 7468). Decodes to an ES256 verifying key.", "type": "string", "examples": [ "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\n-----END PUBLIC KEY-----\n" ] }, "ExternalApproval": { "description": "An approval action requiring external approval from a user group.", "type": "object", "properties": { "threshold": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 1 }, "user_group_id": { "type": "string" } }, "required": [ "user_group_id", "threshold" ] }, "ExternalRuleServerSpecInput": { "type": "object", "properties": { "jwt_alg": { "$ref": "#/components/schemas/JwtAlg" }, "name": { "type": "string" }, "public_key": { "description": "PEM-encoded public key for verifying the rule server's response JWT.\nStructurally validated at request time; cryptographic checks happen on the policy server.", "allOf": [ { "$ref": "#/components/schemas/PemPublicKeyString" } ] }, "url": { "type": "string" } }, "required": [ "name", "url", "public_key", "jwt_alg" ] }, "FreezeBody": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": [ "reason" ] }, "FreezeFilterQuery": { "type": "object", "properties": { "key_ids": { "description": "Comma-separated list of key IDs to freeze/unfreeze", "type": "string" }, "venue_id": { "description": "Venue whose keys to freeze/unfreeze", "type": [ "string", "null" ] } } }, "GetAdminPoliciesResponse": { "description": "A set of admin policies.", "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/AdminPolicyResponse" } } }, "required": [ "policies" ] }, "GetSigningPoliciesResponse": { "description": "A set of signing policies.", "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/SigningPolicyResponse" } } }, "required": [ "policies" ] }, "ImportDecoding": { "type": "string", "enum": [ "raw", "base64", "rfc8032" ] }, "Info": { "type": "object", "properties": { "api_version": { "type": "string" }, "public_key_for_keys_import": { "description": "An RSA PEM public key", "type": "string" } }, "required": [ "api_version", "public_key_for_keys_import" ] }, "JwtAlg": { "type": "string", "enum": [ "ES256", "RS256" ] }, "Key": { "type": "object", "properties": { "display_name": { "type": "string" }, "environment": { "type": "string" }, "freeze_reason": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_frozen": { "type": "boolean" }, "latest_version": { "type": "integer", "format": "uint16", "default": 0, "maximum": 65535, "minimum": 0 }, "scheme": { "$ref": "#/components/schemas/KeyScheme" }, "venue_id": { "type": "string" } }, "required": [ "id", "display_name", "scheme", "venue_id", "environment", "is_frozen" ] }, "KeyDescriptor": { "oneOf": [ { "type": "object", "properties": { "public_key": { "type": "string" }, "scheme": { "type": "string", "const": "Ed25519" } }, "required": [ "scheme", "public_key" ] }, { "type": "object", "properties": { "public_key": { "type": "string" }, "scheme": { "type": "string", "const": "Rsa4096" } }, "required": [ "scheme", "public_key" ] } ] }, "KeyExpirationDate": { "description": "The expiration date can be one of: unset, never, or a date in the format YYYY-MM-DD", "type": "string" }, "KeyFullInformation": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "display_name": { "type": "string" }, "environment": { "type": "string" }, "freeze_reason": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "is_frozen": { "type": "boolean" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "latest_version": { "type": "integer", "format": "uint16", "default": 0, "maximum": 65535, "minimum": 0 }, "metadata": { "type": [ "string", "null" ] }, "scheme": { "$ref": "#/components/schemas/KeyScheme" }, "security_groups": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityGroup" } }, "venue_id": { "type": "string" }, "versions": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/KeyVersionInfo" } } }, "required": [ "id", "display_name", "scheme", "venue_id", "environment", "is_frozen", "security_groups", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "KeyScheme": { "type": "string", "enum": [ "ed25519", "hmac-sha256", "hmac-sha384", "hmac-sha512", "rs256" ] }, "KeyStoresInfo": { "type": "object", "properties": { "mpc_key_stores": { "$ref": "#/components/schemas/MpcKeyStoresInfo" } }, "required": [ "mpc_key_stores" ] }, "KeyVersionInfo": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "expiration_date": { "$ref": "#/components/schemas/KeyExpirationDate" }, "key_descriptor": { "anyOf": [ { "$ref": "#/components/schemas/KeyDescriptor" }, { "type": "null" } ] }, "venue_api_key": { "type": [ "string", "null" ] }, "version": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 0 } }, "required": [ "version", "created_at", "created_by", "expiration_date" ] }, "KeyVersionSelector": { "oneOf": [ { "type": "string", "enum": [ "Latest" ] }, { "type": "object", "properties": { "Specific": { "type": "integer", "format": "uint16", "maximum": 65535, "minimum": 0 } }, "additionalProperties": false, "required": [ "Specific" ] } ] }, "ListAuditLogsQuery": { "type": "object", "properties": { "cursor": { "type": [ "integer", "null" ], "format": "uint64", "minimum": 0 }, "end_time": { "type": [ "string", "null" ], "format": "date-time" }, "event_types": { "description": "Comma-separated list", "type": "string" }, "format": { "description": "Response format: `json` (default, paginated) or `csv` (all matching rows).", "allOf": [ { "$ref": "#/components/schemas/AuditLogFormat" } ], "default": "json" }, "key_ids": { "description": "Comma-separated list", "type": "string" }, "limit": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "performed_by": { "description": "Comma-separated list", "type": "string" }, "start_time": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/AuditLogStatus" }, { "type": "null" } ] }, "topic": { "anyOf": [ { "$ref": "#/components/schemas/AuditLogTopic" }, { "type": "null" } ] } } }, "ListKeysFilterQuery": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ] }, "display_name_like": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "environments": { "description": "Comma-separated list", "type": "string" }, "is_frozen": { "type": [ "boolean", "null" ] }, "key_ids": { "description": "Comma-separated list", "type": "string" }, "limit": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "venue_ids": { "description": "Comma-separated list", "type": "string" } } }, "ListPasskeysResponse": { "description": "Response for `GET /v1/users/{user_id}/passkeys`.", "type": "object", "properties": { "passkeys": { "type": "array", "items": { "$ref": "#/components/schemas/PasskeyInfo" } } }, "required": [ "passkeys" ] }, "ListSecurityGroupsFilterQuery": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ] }, "display_name_like": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "limit": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "members": { "description": "Comma-separated member names/addresses (keys or wallets per the group's\nsigning policy); restricts the listing to groups containing at least one.", "type": "string" }, "signing_policy_id": { "description": "Signing policy that scopes the listing: either the literal `offchain` (the off-chain key-group namespace) or a vault's signing policy, a free-form name equal to the vault's name.", "type": "string" } }, "required": [ "signing_policy_id" ] }, "ListUserGroupsFilterQuery": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ] }, "display_name_like": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "limit": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "members": { "description": "Comma-separated list", "type": "string" } } }, "ListUsersFilterQuery": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ] }, "display_name_like": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "email_contains": { "type": [ "string", "null" ] }, "is_in_groups": { "description": "Comma-separated list", "type": "string" }, "is_type": { "anyOf": [ { "$ref": "#/components/schemas/UserTypeFilter" }, { "type": "null" } ] }, "limit": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "user_ids": { "description": "Comma-separated list", "type": "string" } } }, "ListVenuesFilterQuery": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ] }, "display_name_like": { "description": "Non-case sensitive filter", "type": [ "string", "null" ] }, "import_decodings": { "description": "Comma-separated list", "type": "string" }, "is_seeded": { "type": [ "boolean", "null" ] }, "limit": { "type": [ "integer", "null" ], "format": "uint16", "maximum": 100, "minimum": 1 }, "signing_schemes": { "description": "Comma-separated list", "type": "string" }, "venue_ids": { "description": "Comma-separated list", "type": "string" } } }, "MpcKeyStoreInfo": { "type": "object", "properties": { "api_version": { "type": "string" }, "executor_version": { "type": "string" }, "name": { "type": "string" }, "relay_address": { "type": "string" }, "service_version": { "type": "string" } }, "required": [ "name", "api_version", "service_version", "executor_version", "relay_address" ] }, "MpcKeyStoresInfo": { "type": "object", "properties": { "stores": { "type": "array", "items": { "$ref": "#/components/schemas/MpcKeyStoreInfo" } } }, "required": [ "stores" ] }, "NetworkFamily": { "description": "Network family a wallet belongs to. Selects both the BIP-44 coin type used\nwhen deriving the wallet's address and the signing curve.", "type": "string", "enum": [ "evm", "solana" ] }, "OrchestratorInfo": { "type": "object", "properties": { "api_version": { "type": "string" }, "service_version": { "type": "string" } }, "required": [ "api_version", "service_version" ] }, "Page": { "description": "A page of results returned by a paginated query.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserFullInformation" } }, "next_cursor": { "description": "Cursor pointing past the last item in this page.\n`None` means there are no more results.", "anyOf": [ { "$ref": "#/components/schemas/Cursor" }, { "type": "null" } ] }, "total": { "description": "Total number of items matching the filter (across all pages).", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "items", "total" ] }, "Page2": { "description": "A page of results returned by a paginated query.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KeyFullInformation" } }, "next_cursor": { "description": "Cursor pointing past the last item in this page.\n`None` means there are no more results.", "anyOf": [ { "$ref": "#/components/schemas/Cursor" }, { "type": "null" } ] }, "total": { "description": "Total number of items matching the filter (across all pages).", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "items", "total" ] }, "Page3": { "description": "A page of results returned by a paginated query.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserGroupFullInformation" } }, "next_cursor": { "description": "Cursor pointing past the last item in this page.\n`None` means there are no more results.", "anyOf": [ { "$ref": "#/components/schemas/Cursor" }, { "type": "null" } ] }, "total": { "description": "Total number of items matching the filter (across all pages).", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "items", "total" ] }, "Page4": { "description": "A page of results returned by a paginated query.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityGroupFullInformation" } }, "next_cursor": { "description": "Cursor pointing past the last item in this page.\n`None` means there are no more results.", "anyOf": [ { "$ref": "#/components/schemas/Cursor" }, { "type": "null" } ] }, "total": { "description": "Total number of items matching the filter (across all pages).", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "items", "total" ] }, "Page5": { "description": "A page of results returned by a paginated query.", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VenueResponse" } }, "next_cursor": { "description": "Cursor pointing past the last item in this page.\n`None` means there are no more results.", "anyOf": [ { "$ref": "#/components/schemas/Cursor" }, { "type": "null" } ] }, "total": { "description": "Total number of items matching the filter (across all pages).", "type": "integer", "format": "uint64", "minimum": 0 } }, "required": [ "items", "total" ] }, "PasskeyInfo": { "description": "A single enrolled passkey.", "type": "object", "properties": { "credential_id": { "description": "Base64url-encoded WebAuthn credential ID. No raw COSE key or attestation data is returned.", "type": "string" }, "device_name": { "type": "string" }, "enrolled_at": { "type": "string", "format": "date-time" } }, "required": [ "device_name", "enrolled_at", "credential_id" ] }, "PemPublicKeyString": { "description": "PEM-encoded SubjectPublicKeyInfo (RFC 7468). Validated structurally at request time; cryptographic checks happen on the policy server.", "type": "string", "examples": [ "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\n-----END PUBLIC KEY-----\n" ] }, "PolicyServerReaderInfo": { "type": "object", "properties": { "api_version": { "type": "string" }, "external_rule_server_signing_pubkey": { "$ref": "#/components/schemas/Es256PublicKey" }, "name": { "type": "string" }, "service_version": { "type": "string" } }, "required": [ "name", "api_version", "service_version", "external_rule_server_signing_pubkey" ] }, "PolicyServerWriterInfo": { "type": "object", "properties": { "api_version": { "type": "string" }, "name": { "type": "string" }, "service_version": { "type": "string" } }, "required": [ "name", "api_version", "service_version" ] }, "PolicyServersInfo": { "type": "object", "properties": { "readers": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyServerReaderInfo" } }, "writers": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyServerWriterInfo" } } }, "required": [ "readers", "writers" ] }, "PublicKeyEncoding": { "type": "string", "enum": [ "pem", "csr" ] }, "RemovePasskeyRequest": { "description": "Body for `DELETE /v1/users/{user_id}/passkeys` (signed request).", "type": "object", "properties": { "device_name": { "type": "string" } }, "required": [ "device_name" ] }, "RotateKeyRequest": { "type": "object", "properties": { "encrypted_private_key": { "type": [ "string", "null" ] }, "expiration_date": { "allOf": [ { "$ref": "#/components/schemas/KeyExpirationDate" } ], "default": "unset" }, "venue_api_key": { "type": [ "string", "null" ] } } }, "SecurityGroup": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "signing_policy_id": { "type": "string" } }, "required": [ "id", "display_name", "signing_policy_id" ] }, "SecurityGroupFullInformation": { "description": "A security group's members, tagged by kind in `member_type`. A group is homogeneous: an\noff-chain group reports `Keys`, a vault group reports `Wallets` (including\nthe empty case, where the kind comes from the signing policy).", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "signing_policy_id": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "member_type": { "type": "string", "const": "keys" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } }, "required": [ "member_type", "members" ] }, { "type": "object", "properties": { "member_type": { "type": "string", "const": "wallets" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } }, "required": [ "member_type", "members" ] } ], "required": [ "id", "display_name", "signing_policy_id", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "SignRequest": { "type": "object", "properties": { "extra_data": { "type": [ "string", "null" ] }, "key_version": { "allOf": [ { "$ref": "#/components/schemas/KeyVersionSelector" } ], "default": "latest" }, "message": { "type": "string" } }, "required": [ "message" ] }, "SignatureResponse": { "type": "object", "properties": { "signature": { "type": "string" } }, "required": [ "signature" ] }, "SigningConditionInput": { "type": "string", "enum": [ "raw_signing" ] }, "SigningPolicyResponse": { "description": "A single signing policy.", "type": "object", "properties": { "policy_id": { "type": "string" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/SigningRuleInput" } }, "version_number": { "type": "integer", "format": "uint32", "minimum": 0 } }, "required": [ "policy_id", "version_number", "rules" ] }, "SigningPolicyScope": { "description": "The set of signing policies an admin rule applies to.\n\nMirrors `policy_engine::SigningPolicyScope`, kept as a separate copy so\n`external-api-types` does not depend on `policy-engine`.", "oneOf": [ { "description": "Applies to any signing policy.", "type": "string", "const": "Any" }, { "description": "Applies only to the listed signing policies (an empty list never matches).", "type": "object", "properties": { "Only": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "Only" ] } ] }, "SigningPolicySetRequest": { "type": "object", "properties": { "previous_version": { "type": "integer", "format": "uint32", "minimum": 0 }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/SigningRuleInput" } } }, "required": [ "previous_version", "rules" ] }, "SigningResultInput": { "description": "Rule result for a signing-policy rule.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "approve" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "deny" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "external_approval" } }, "allOf": [ { "$ref": "#/components/schemas/ExternalApproval" } ], "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "external_rule_server" } }, "allOf": [ { "$ref": "#/components/schemas/ExternalRuleServerSpecInput" } ], "required": [ "type" ] } ] }, "SigningRuleInput": { "description": "A single rule in a signing policy.", "type": "object", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/SigningConditionInput" } }, "key_in_groups": { "type": "array", "items": { "type": "string" } }, "result": { "$ref": "#/components/schemas/SigningResultInput" }, "rule_index": { "type": "integer", "format": "uint32", "minimum": 1 }, "user_in_groups": { "type": "array", "items": { "type": "string" } } }, "required": [ "rule_index", "user_in_groups", "key_in_groups", "conditions", "result" ] }, "SystemInfo": { "type": "object", "properties": { "key_stores_info": { "$ref": "#/components/schemas/KeyStoresInfo" }, "orchestrator_info": { "$ref": "#/components/schemas/OrchestratorInfo" }, "policy_servers_info": { "$ref": "#/components/schemas/PolicyServersInfo" } }, "required": [ "orchestrator_info", "policy_servers_info", "key_stores_info" ] }, "UpdateKeyRequest": { "description": "Partial update (PATCH) request for a key.\n\nUses merge-patch semantics: only fields present in the request body are\nupdated; omitted fields are left unchanged.\n\n- `display_name`: set to update the key's display name; omit keeping the current value.\n- `environment`: set to update the key's environment; omit keeping the current value.\n- `metadata`: omit leaving unchanged, set to a string to update, set to `null` to clear.\n- `versions`: list of per-version updates to apply. An empty list (or omitted) means\n no version-level changes.", "type": "object", "properties": { "display_name": { "type": [ "string", "null" ] }, "environment": { "type": [ "string", "null" ] }, "metadata": { "type": [ "string", "null" ] }, "versions": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/UpdateKeyVersionRequest" } } } }, "UpdateKeyVersionRequest": { "description": "A version-level update within a [`UpdateKeyRequest`].\n\nSpecifies which version to target (by number or `\"latest\"`) and the new\nvalues for that version's mutable fields. Uses the same merge-patch\nsemantics as [`UpdateKeyRequest`]: omitted fields are left unchanged.\n\n- `venue_api_key`: omit leaving unchanged, set to a string to update, set to `null` to clear.\n- `expiration_date`: omit leaving unchanged, set to update.", "type": "object", "properties": { "expiration_date": { "anyOf": [ { "$ref": "#/components/schemas/KeyExpirationDate" }, { "type": "null" } ] }, "venue_api_key": { "type": [ "string", "null" ] }, "version": { "description": "Which version to update. Defaults to `\"latest\"` when omitted.", "allOf": [ { "$ref": "#/components/schemas/KeyVersionSelector" } ], "default": "latest" } } }, "UpdateSecurityGroupMembersRequest": { "type": "object", "properties": { "members": { "description": "Member names/addresses to add. Interpreted as keys or wallets per the\ngroup's signing policy.", "type": "array", "items": { "type": "string" } } }, "required": [ "members" ] }, "UpdateSecurityGroupRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "members": { "description": "Replacement member names/addresses (keys or wallets per the group's\nsigning policy); empty clears membership.", "type": "array", "items": { "type": "string" } } }, "required": [ "display_name" ] }, "UpdateUserGroupMembersRequest": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "user_ids" ] }, "UpdateUserGroupRequest": { "description": "This request is used to update the state of a user group.\nIt will replace the display_name, description, and the list of members with the given values", "type": "object", "properties": { "description": { "description": "Setting the description with `null` clears the description.", "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "user_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "display_name", "user_ids" ] }, "UpdateUserRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" } }, "required": [ "display_name" ] }, "UpdateVenueRequest": { "type": "object", "properties": { "display_name": { "type": "string" } }, "required": [ "display_name" ] }, "UserFullInformation": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "user_groups": { "type": "array", "items": { "$ref": "#/components/schemas/UserGroup" } } }, "oneOf": [ { "type": "object", "properties": { "cloud_provider": { "$ref": "#/components/schemas/CloudProvider" }, "email": { "type": "string" }, "type": { "type": "string", "const": "human" } }, "required": [ "type", "email", "cloud_provider" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "machine" } }, "required": [ "type" ] } ], "required": [ "id", "display_name", "user_groups", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "UserGroup": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "display_name" ] }, "UserGroupFullInformation": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/UserInfo" } } }, "required": [ "id", "display_name", "members", "created_at", "created_by", "last_updated_at", "last_updated_by" ] }, "UserInGroups": { "description": "Which users a rule applies to: either any authenticated user or members of specific groups.", "anyOf": [ { "description": "Any authenticated user.", "allOf": [ { "$ref": "#/components/schemas/AnyUser" } ] }, { "description": "Users belonging to one of the listed groups.", "type": "array", "items": { "type": "string" } } ] }, "UserInfo": { "type": "object", "properties": { "display_name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "display_name" ] }, "UserTypeFilter": { "type": "string", "enum": [ "human", "machine" ] }, "VenueResponse": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "display_name": { "type": "string" }, "id": { "type": "string" }, "is_seeded": { "type": "boolean" }, "last_updated_at": { "type": "string", "format": "date-time" }, "last_updated_by": { "type": "string" } }, "oneOf": [ { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha256" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha384" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "signing_scheme": { "type": "string", "const": "hmac-sha512" } }, "required": [ "signing_scheme", "import_decoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "public_key_encoding": { "$ref": "#/components/schemas/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "ed25519" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] }, { "type": "object", "properties": { "import_decoding": { "$ref": "#/components/schemas/ImportDecoding" }, "public_key_encoding": { "$ref": "#/components/schemas/PublicKeyEncoding" }, "signing_scheme": { "type": "string", "const": "rs256" } }, "required": [ "signing_scheme", "import_decoding", "public_key_encoding" ] } ], "required": [ "id", "display_name", "is_seeded", "created_by", "created_at", "last_updated_by", "last_updated_at" ] }, "Wallet": { "type": "object", "properties": { "address": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "network_family": { "$ref": "#/components/schemas/NetworkFamily" } }, "required": [ "address", "display_name", "network_family" ] }, "WhoamiResponse": { "type": "object", "properties": { "capabilities": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CapabilityStatus" } }, "display_name": { "type": "string" }, "groups": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "manage_signing_policies_for_vaults": { "description": "The vaults which this user may edit signing policies and security groups for.", "allOf": [ { "$ref": "#/components/schemas/SigningPolicyScope" } ] }, "passkeys": { "type": "array", "default": [], "items": { "$ref": "#/components/schemas/PasskeyInfo" } } }, "oneOf": [ { "type": "object", "properties": { "cloud_provider": { "$ref": "#/components/schemas/CloudProvider" }, "email": { "type": "string" }, "type": { "type": "string", "const": "human" } }, "required": [ "type", "email", "cloud_provider" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "machine" } }, "required": [ "type" ] } ], "required": [ "id", "display_name", "groups", "capabilities", "manage_signing_policies_for_vaults" ] } } }, "tags": [ { "name": "AdminPolicies", "description": "Admin policy management operations" }, { "name": "SigningPolicies", "description": "Signing policy management operations" }, { "name": "AuditLogs", "description": "Audit log operations" }, { "name": "Auth", "description": "Authentication and credential management" }, { "name": "Common", "description": "Common API operations" }, { "name": "Keys", "description": "Key management operations" }, { "name": "Users", "description": "User management operations" }, { "name": "UserGroups", "description": "User group management operations" }, { "name": "SecurityGroups", "description": "Security group management operations" }, { "name": "Whoami", "description": "Current user identity and capabilities" }, { "name": "KeysBackup", "description": "Keys backup operations" }, { "name": "Venues", "description": "Venue management operations" }, { "name": "Docs", "description": "OpenAPI specification documents" } ] }