{ "openapi": "3.1.0", "info": { "title": "Calimero node API", "version": "1", "description": "Every route a `merod` node serves, on one HTTP API at its `--listen` address. The route table is `router` in `crates/node/src/api.rs`; this document is generated from the registry next to it (`crates/node/src/api/openapi.rs`), whose tests hold it to that table.\n\n**Requests are sealed.** Only `GET /health` and `GET /attestation` travel in the clear. Every other request goes inside the sealed channel (`calimero-sealed`, wire format v2, Noise NK) to the transport key the node's attestation binds, after the client checked the quote against a mero-tee release it trusts; a TDX node refuses plain requests (a node started with `--dev` accepts them). A generic HTTP tool (curl, Postman, a generated client) therefore reaches only those two routes: use a sealing client (`meroctl`, `calimero-client` for Rust, mero-js `CalimeroClient`, calimero-client-py `CloudClient`), or put such a client's transport under the generated code. The paths, bodies and answers below are what travels inside the channel.\n\n**Errors** answer `{ status, error, message, details? }`: `error` is the code, `details` says more (the challenge of a `412 CONFIRM_REQUIRED`, the statement of a `428 OPERATOR_SIGNATURE_REQUIRED`, `leaderUrl` of a `421 NOT_LEADER`). Each operation lists the codes it raises itself and those its credential implies, per status in `x-calimero-codes` (every error answer is the one `Error` schema); any operation may also answer `400 BAD_REQUEST`, `400 REJECTED`, `421 NOT_LEADER` and `503 UNAVAILABLE`. A route that takes a session may answer `421 WRONG_NODE` (no `details`): try another node. `x-calimero-details` on an error response maps each of its codes that carries `details` to that value's schema, and `x-calimero-error-details` at the root maps every such code: one code, one schema, so a client reads `details` by `error`.\n\n**Retries.** `x-calimero-retry-safe` marks the operations a client may send again after a `503` or a lost answer (`x-calimero-retry-requires` names the body field that makes it so, an idempotency key). The sealed channel's own `503` (`{ error: { code: \"busy\", message } }`, outside the envelope: too many sealed requests or sessions at once; the schema `x-calimero-sealed-refusal` names) carries `Retry-After: 1` on any sealed route; the node's `503 UNAVAILABLE` answers carry none. `x-calimero-step-up` (with `x-calimero-user-verification`, and `x-calimero-step-up-when` where it applies only sometimes) and `x-calimero-operator` mark the two-round operations below.\n\n**Numbers** that may exceed 2^53 (fuel, bytes) travel as decimal strings (D20); every other integer is `format: int64` (read it into a 64-bit integer), and stays below 2^53.", "license": { "name": "MIT OR Apache-2.0", "identifier": "MIT OR Apache-2.0" } }, "servers": [ { "url": "https://{node}", "description": "A node's --listen address, reached through the sealed channel.", "variables": { "node": { "default": "localhost:2428" } } } ], "tags": [ { "name": "Public", "description": "In the clear (`/health`, `/attestation`) or sealed without a credential." }, { "name": "Accounts", "description": "Sign-up, sign-in, passkeys, sessions, API keys and the account's own approvals." }, { "name": "Packages", "description": "Signed releases (`.mpk`), raw bundles and frontend origins." }, { "name": "Apps", "description": "App instances (contexts): calls, views, events, upgrades, blobs and sealed files." }, { "name": "Organizations", "description": "Organizations, members, teams, invites, approvals and upgrade runs." }, { "name": "Consent", "description": "Approvals an app's frontend asks for on the node's own consent page." }, { "name": "Sign-up and deployments", "description": "The cluster's owner: the sign-up policy, deployers and deployments." }, { "name": "Ops", "description": "The operator's routes: every one needs the ops token; decisions are signed with the operator key." } ], "x-calimero-error-details": { "APP_ERROR": { "$ref": "#/components/schemas/AppError" }, "BAD_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" }, "COMPUTE_ABI_MISMATCH": { "$ref": "#/components/schemas/ServiceRefused" }, "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" }, "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" }, "FILES_UNAVAILABLE": { "$ref": "#/components/schemas/RetryAfter" }, "INIT_FAILED": { "$ref": "#/components/schemas/InitFailed" }, "NOT_LEADER": { "$ref": "#/components/schemas/NotLeader" }, "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" }, "PART_CONFLICT": { "$ref": "#/components/schemas/UploadPosition" }, "PART_OUT_OF_ORDER": { "$ref": "#/components/schemas/UploadPosition" }, "RECOVERY_NOT_READY": { "$ref": "#/components/schemas/RecoveryNotReady" }, "RELEASE_DEADLINE": { "$ref": "#/components/schemas/ReleaseDeadline" }, "RUNTIME_TOO_OLD": { "$ref": "#/components/schemas/RuntimeTooOld" }, "TIMEOUT": { "$ref": "#/components/schemas/RetryAfter" }, "TRAP": { "$ref": "#/components/schemas/Trap" }, "UNSUPPORTED_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" }, "UPGRADE_FAILED": { "$ref": "#/components/schemas/Applied" }, "UPGRADE_PENDING": { "$ref": "#/components/schemas/UpgradePending" }, "UPLOAD_INCOMPLETE": { "$ref": "#/components/schemas/UploadPosition" } }, "x-calimero-sealed-refusal": { "$ref": "#/components/schemas/SealedRefusal" }, "paths": { "/apps": { "post": { "operationId": "app_create", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Create an app instance", "description": "From a release (`package`, `version`, `service`), a deployment's offer (`deployment`), or an uploaded `bundle`; in an organization (`org`), or, naming none, the caller's personal organization. Every app is in an organization. `initArgs` go to the app's `init` and `metadata` is kept as given (both free-form JSON). Answers once `init` committed; `compute` says whether the app has a compute component.\n\n**Who:** an installer (an account holder, or an unscoped API key that is not read-only).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "an installer (an account holder, or an unscoped API key that is not read-only)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "bundle": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" }, "service": { "type": "string" }, "org": { "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "initArgs": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "deployment": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "contextId": { "type": "string" }, "group": { "type": "integer", "format": "int64", "minimum": 0 }, "replicas": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "compute": { "type": "boolean" } }, "required": [ "appId", "contextId", "group", "replicas", "compute" ] } } } }, "400": { "description": "`AMBIGUOUS_COMPUTE`; `BAD_REQUEST`: the request is malformed; `NOT_OFFERED`; `NO_SUCH_SERVICE`; `VERSION_REQUIRED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "AMBIGUOUS_COMPUTE", "BAD_REQUEST", "NOT_OFFERED", "NO_SUCH_SERVICE", "VERSION_REQUIRED" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`RELEASE_DEADLINE`; `RUNTIME_TOO_OLD`. `details` of `RELEASE_DEADLINE`: a `ReleaseDeadline`, `RUNTIME_TOO_OLD`: a `RuntimeTooOld`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RELEASE_DEADLINE", "RUNTIME_TOO_OLD" ], "x-calimero-details": { "RELEASE_DEADLINE": { "$ref": "#/components/schemas/ReleaseDeadline" }, "RUNTIME_TOO_OLD": { "$ref": "#/components/schemas/RuntimeTooOld" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "422": { "description": "`INIT_FAILED`. `details` of `INIT_FAILED`: a `InitFailed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "INIT_FAILED" ], "x-calimero-details": { "INIT_FAILED": { "$ref": "#/components/schemas/InitFailed" } } }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] }, "503": { "description": "`UNAVAILABLE`: the cluster cannot answer now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAVAILABLE" ] } } }, "get": { "operationId": "app_list", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Apps the caller reaches", "description": "Anyone may list public apps.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "bundle", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "$ref": "#/components/schemas/AppEntry" } } }, "required": [ "apps" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}": { "get": { "operationId": "app_get", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "One app", "description": "`{app}` is an app id or its context id (`hex(SHA-256(app_id))`), here and on every `/apps/{app}` route.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "app_delete", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Delete an app", "description": "The owner or an organization admin.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "appId", "deleted" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/abi": { "get": { "operationId": "app_abi", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "An app's ABI", "description": "The ABI its bundle embeds: methods, events, errors and state. `abi` is the bundle's own document, free-form here: its format is the ABI's, not this API's.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "string" }, "abi": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "bundle", "abi" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/access": { "post": { "operationId": "app_access", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Set who may reach an app", "description": "A package-bound session: only its own package's app, from one of its package's teams to another.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "$ref": "#/components/schemas/Access" } }, "required": [ "access" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/attestation": { "get": { "operationId": "app_attestation", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Every replica's receipt-key attestation", "description": "Each replica's `/attestation?purpose=receipts` for `nonce` (32 bytes, hex), or why it could not be had (`error`), and `cluster`, the cluster id each quote binds (with the replica's `node`): the documents are fetched in the clear, so their own `cluster` and `node` fields count for nothing. Any other query parameter is ignored.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "nonce", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "cluster": { "type": "string" }, "replicas": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "attestation": { "$ref": "#/components/schemas/AttestationDoc" } }, "required": [ "node", "attestation" ] }, { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "type": "string" } }, "required": [ "node", "error" ] } ] } } }, "required": [ "appId", "cluster", "replicas" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/blobs": { "post": { "operationId": "blob_upload", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Upload a blob", "description": "A plain blob, stored with the request's `Content-Type`, which a component app's download answers with: any media type (printable ASCII, 127 bytes at most; another is `400 BAD_REQUEST`), `application/octet-stream` when the request names none. Send the blob's own type, not `*/*`, which would be stored as its type. Any `sealed` parameter, `true` or `false`, is refused `400 USE_FILES_API`: sealed files go through `/files`.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sealed", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } }, "description": "the blob; its `Content-Type` is the type it is stored and served with" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "blobId": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "index": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "blobId", "id", "size", "index" ] } } } }, "400": { "description": "`USE_FILES_API`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "USE_FILES_API" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] } } }, "get": { "operationId": "blob_list", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "List an app's blobs", "description": "Plain blobs only.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "blobs": { "type": "array", "items": { "type": "object", "properties": { "blobId": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "blobId", "id", "size" ] } } }, "required": [ "blobs" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/blobs/{id}": { "get": { "operationId": "blob_download", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Download a blob", "description": "`{id}` is base58 or hex; `grant` is a link the app made (`BlobRef::grant`).\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "grant", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK: the blob: a component app's under the MIME type it was stored with, otherwise `application/octet-stream`.", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "503": { "description": "`UNAVAILABLE`: the cluster cannot answer now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAVAILABLE" ] } } }, "delete": { "operationId": "blob_delete", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Forget a blob", "description": "The owner or an organization admin.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "index" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/blobs/{id}/info": { "get": { "operationId": "blob_info", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "A blob's size", "description": "**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "blobId": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "blobId", "id", "size" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`NOT_SUPPORTED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_SUPPORTED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/blobs/{id}/revoke": { "post": { "operationId": "blob_revoke", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Invalidate a blob's grants", "description": "The grants made so far for a published blob; the owner or an organization admin.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "index" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/events": { "get": { "operationId": "events", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "An app's events as server-sent events", "description": "Committed events from index `from`, then live ones, each to its audience.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Server-sent events: each committed event the caller is in the audience of.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`RATE_LIMITED`: a node's limit on open streams or ceremonies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RATE_LIMITED" ] }, "503": { "description": "`UNAVAILABLE`: the cluster cannot answer now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAVAILABLE" ] } } } }, "/apps/{app}/files": { "post": { "operationId": "files_upload", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Upload a sealed file", "description": "Up to 16 MiB in one request; the owner and the organization's members.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream" } } }, "description": "the file" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "blobId": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string" }, "index": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "blobId", "id", "size", "sha256", "index" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] } } }, "get": { "operationId": "files_list", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "List an app's sealed files", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "blobId": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string" } }, "required": [ "blobId", "id", "size", "sha256" ] } } }, "required": [ "files" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/files/uploads": { "post": { "operationId": "upload_begin", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Begin a file upload", "description": "A session for a file of `size` bytes, sent in parts of `partBytes`.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "size": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "size" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "partBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "parts": { "type": "integer", "format": "int64", "minimum": 0 }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "uploadId", "partBytes", "parts", "expiresAt" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] } } } }, "/apps/{app}/files/uploads/{upload}": { "get": { "operationId": "upload_status", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Where an upload is", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "upload", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string" }, "partBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "parts": { "type": "integer", "format": "int64", "minimum": 0 }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "next": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "uploadId", "partBytes", "parts", "expiresAt", "size", "next" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "upload_abort", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Abort an upload", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "upload", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/files/uploads/{upload}/complete": { "post": { "operationId": "upload_complete", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Commit an upload", "description": "Charges and commits the file; a retry answers the same file. `409 UPLOAD_INCOMPLETE` names the part still missing.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "upload", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "blobId": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string" }, "index": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "blobId", "id", "size", "sha256", "index" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "409": { "description": "`UPLOAD_INCOMPLETE`. `details` of `UPLOAD_INCOMPLETE`: a `UploadPosition`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UPLOAD_INCOMPLETE" ], "x-calimero-details": { "UPLOAD_INCOMPLETE": { "$ref": "#/components/schemas/UploadPosition" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/files/uploads/{upload}/parts/{k}": { "put": { "operationId": "upload_part", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Send one part", "description": "Part `k` (from 0), raw bytes; a part out of order (`409 PART_OUT_OF_ORDER`), or one that differs from the part sent before as `k` (`409 PART_CONFLICT`), answers the next one expected in `details.next`.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "upload", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "k", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream" } } }, "description": "the part" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "next": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "next" ] } } } }, "400": { "description": "`BAD_PART`; `BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_PART", "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "409": { "description": "`PART_CONFLICT`; `PART_OUT_OF_ORDER`. `details` of `PART_CONFLICT`: a `UploadPosition`, `PART_OUT_OF_ORDER`: a `UploadPosition`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "PART_CONFLICT", "PART_OUT_OF_ORDER" ], "x-calimero-details": { "PART_CONFLICT": { "$ref": "#/components/schemas/UploadPosition" }, "PART_OUT_OF_ORDER": { "$ref": "#/components/schemas/UploadPosition" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "503": { "description": "`FILES_UNAVAILABLE`. `details` of `FILES_UNAVAILABLE`: a `RetryAfter`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FILES_UNAVAILABLE" ], "x-calimero-details": { "FILES_UNAVAILABLE": { "$ref": "#/components/schemas/RetryAfter" } } } } } }, "/apps/{app}/files/{id}": { "get": { "operationId": "file_info", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "One sealed file", "description": "Its plaintext size and SHA-256, never its key.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "blobId": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string" } }, "required": [ "blobId", "id", "size", "sha256" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/files/{id}/export": { "post": { "operationId": "exports_export", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Export a sealed file's key", "description": "The owner and the organization's members. `recipient` is an X25519 public key (64 hex characters); the file's data key comes back wrapped to it, with the file's `segments` (each one's hash, hex) and `ephemeral` public key. The node never answers plaintext or a key in the clear. 30 a minute per account.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string" } }, "required": [ "recipient" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "type": "string" }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string" }, "segments": { "type": "array", "items": { "type": "string" } }, "ephemeral": { "type": "string" }, "wrapped": { "type": "string" } }, "required": [ "app", "id", "size", "sha256", "segments", "ephemeral", "wrapped" ] } } } }, "400": { "description": "`BAD_RECIPIENT`; `BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_RECIPIENT", "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`TOO_MANY_EXPORTS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_MANY_EXPORTS" ] } } } }, "/apps/{app}/files/{id}/segments/{k}": { "get": { "operationId": "exports_segment", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "One segment of a sealed file", "description": "Segment `k` (from 0) of the file's ciphertext, raw; the owner and the organization's members.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "k", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK: the segment's ciphertext, `application/octet-stream`.", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see; `NO_SUCH_SEGMENT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND", "NO_SUCH_SEGMENT" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/intents": { "post": { "operationId": "intents", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Call a method", "description": "A logged call: the result, the events of the call the caller receives, and the answering node's receipt. A `confirm` method answers `412` first. An app error is `422 APP_ERROR` with `details { index, code, fields }`; a trap `422 TRAP`. `args`, `result` and each event's `data` are the app's own JSON, free-form here: the app's ABI (`GET /apps/{app}/abi`, or its OpenAPI document) types them.\n\n**Who:** whoever the app's access admits (a public app: anyone). **Step-up:** when the method is a `confirm` method of the app's ABI, answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "x-calimero-step-up-when": "the method is a `confirm` method of the app's ABI", "x-calimero-retry-safe": true, "x-calimero-retry-requires": "idempotencyKey", "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "args": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "idempotencyKey": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "method" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "result": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "events": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "data": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "kind", "data" ] } }, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "required": [ "index", "result", "events", "receipt" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`RELEASE_DEADLINE`. `details` of `RELEASE_DEADLINE`: a `ReleaseDeadline`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RELEASE_DEADLINE" ], "x-calimero-details": { "RELEASE_DEADLINE": { "$ref": "#/components/schemas/ReleaseDeadline" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "413": { "description": "`ARGS_TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "ARGS_TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "422": { "description": "`APP_ERROR`; `TRAP`. `details` of `APP_ERROR`: a `AppError`, `TRAP`: a `Trap`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "APP_ERROR", "TRAP" ], "x-calimero-details": { "APP_ERROR": { "$ref": "#/components/schemas/AppError" }, "TRAP": { "$ref": "#/components/schemas/Trap" } } }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] }, "503": { "description": "`TIMEOUT`; `UNAVAILABLE`: the cluster cannot answer now. `details` of `TIMEOUT`: a `RetryAfter`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TIMEOUT", "UNAVAILABLE" ], "x-calimero-details": { "TIMEOUT": { "$ref": "#/components/schemas/RetryAfter" } } } } } }, "/apps/{app}/metadata": { "post": { "operationId": "app_metadata", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Set an app's metadata", "description": "The owner or an organization admin; 16 KiB at most. `metadata` is the caller's own JSON, free-form, kept as given.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/methods/{method}": { "post": { "operationId": "app_method", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Call a method by its path", "description": "The body of `/intents` or `/views` without `method`, which the path names, as the app's OpenAPI document lists it: a view the running bundle's ABI declares (without `confirm`) is answered as `/views`, anything else as `/intents`, with that route's gate, step-up and limits. Retry-safe as a view always, as a call with `idempotencyKey`. `args`, `result` and each event's `data` are the app's own JSON, free-form here: the app's ABI (`GET /apps/{app}/abi`, or its OpenAPI document) types them.\n\n**Who:** whoever the app's access admits (a public app: anyone). **Step-up:** when the method is a `confirm` method of the app's ABI, answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "x-calimero-step-up-when": "the method is a `confirm` method of the app's ABI", "x-calimero-retry-safe": true, "x-calimero-retry-requires": "idempotencyKey", "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "method", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "args": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "idempotencyKey": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" }, "consistency": { "type": "string", "enum": [ "strong", "stale" ] }, "minIndex": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "result": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "events": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "data": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "kind", "data" ] } }, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "required": [ "index", "result", "receipt" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `RESERVED_METHOD`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "RESERVED_METHOD", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`RELEASE_DEADLINE`. `details` of `RELEASE_DEADLINE`: a `ReleaseDeadline`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RELEASE_DEADLINE" ], "x-calimero-details": { "RELEASE_DEADLINE": { "$ref": "#/components/schemas/ReleaseDeadline" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "413": { "description": "`ARGS_TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "ARGS_TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "422": { "description": "`APP_ERROR`; `TRAP`. `details` of `APP_ERROR`: a `AppError`, `TRAP`: a `Trap`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "APP_ERROR", "TRAP" ], "x-calimero-details": { "APP_ERROR": { "$ref": "#/components/schemas/AppError" }, "TRAP": { "$ref": "#/components/schemas/Trap" } } }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] }, "503": { "description": "`NOT_CAUGHT_UP`; `TIMEOUT`; `UNAVAILABLE`: the cluster cannot answer now. `details` of `TIMEOUT`: a `RetryAfter`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_CAUGHT_UP", "TIMEOUT", "UNAVAILABLE" ], "x-calimero-details": { "TIMEOUT": { "$ref": "#/components/schemas/RetryAfter" } } } } } }, "/apps/{app}/move": { "post": { "operationId": "app_move", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Move an app to another organization", "description": "Its data where it is; its files, runs and quotas go to the target, `org` or app-team access becomes the target's app team of its package. `bringMembers` adds the source's members who reach it, capped at `member`. `from` is the organization it left, `null` for an app of the caller's own; `added` the accounts brought; `revokedInvites` how many invites to its old team were withdrawn.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toOrg": { "type": "string" }, "bringMembers": { "type": "boolean" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "toOrg" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "org": { "type": "string" }, "access": { "$ref": "#/components/schemas/Access" }, "created": { "type": "boolean" }, "added": { "type": "array", "items": { "type": "string" } }, "revokedInvites": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "appId", "from", "org", "access", "created", "added", "revokedInvites" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/openapi.json": { "get": { "operationId": "app_openapi", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "An app's OpenAPI document", "description": "Generated from the ABI of the bundle the app runs, under the access `/abi` has: one `POST /apps/{app}/methods/{method}` per method, with its arguments, result and errors. Free-form here: it is a document of its own, which a client reads as OpenAPI.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "410": { "description": "`UNSUPPORTED_ENGINE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNSUPPORTED_ENGINE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "422": { "description": "`BAD_ABI`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_ABI" ] } } } }, "/apps/{app}/pipeline-runs": { "get": { "operationId": "pipelines_list", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "An app's pipeline runs", "description": "The recent runs, newest first, as `{ runs }`; `limit` 1 to 100. Sizes, hashes and results only for callers who may list the app's files.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "`BAD_LIMIT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_LIMIT" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/pipeline-runs/{run}": { "get": { "operationId": "pipelines_get", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "One pipeline run", "description": "Its record: `state`, `version`, `hash`, `computeBundle`, `inputs`, `params`, per-step `status`, `runs`, `outputs`, `result`, `reason` and `cost` (`cost` and `costSoFar` for a run with a cap). Sizes, hashes and results only for callers who may list the app's files.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/pipeline-runs/{run}/cancel": { "post": { "operationId": "pipelines_cancel", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Cancel a pipeline run", "description": "The owner and the organization's members. Its pending steps end cancelled and its running steps' runs stop.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "string" } }, "required": [ "run" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/pipeline-runs/{run}/events": { "get": { "operationId": "pipeline_events_events", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "A pipeline run as server-sent events", "description": "Whoever may read the run. Metadata only; at most 64 streams per app per node, and one lasts an hour.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-sent events: a `snapshot`, then `run` and `step` per change, then `end`, and the stream closes.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`TOO_MANY_SUBSCRIBERS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_MANY_SUBSCRIBERS" ] } } } }, "/apps/{app}/pipeline-runs/{run}/receipt": { "get": { "operationId": "pipeline_receipt_receipt", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "A pipeline run's receipt", "description": "The owner and the organization's members. For an ended run: the receipt, the answering node and its signature over it, by the node's receipt key.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipt": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "node": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "receipt", "node", "signature" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`RUN_NOT_ENDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RUN_NOT_ENDED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/pipeline-runs/{run}/retry": { "post": { "operationId": "pipelines_retry", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Retry a pipeline run", "description": "The owner and the organization's members. A new run of an ended run's pipeline at the same release, hash and compute component, with the same inputs and params, the `limits` applied and `retryOf` set. `202`.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limits": { "type": "object", "additionalProperties": { "type": "object", "properties": { "fuel": { "type": "integer", "format": "int64", "minimum": 0 }, "memoryMib": { "type": "integer", "format": "int64", "minimum": 0 }, "wallSecs": { "type": "integer", "format": "int64", "minimum": 0 } } } }, "maxCost": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "string" }, "retryOf": { "type": "string" }, "worstCase": { "type": "string" } }, "required": [ "run", "retryOf" ] } } } }, "400": { "description": "`BAD_LIMITS`; `BAD_MAX_COST`; `LIMIT_EXCEEDS_CAP`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_LIMITS", "BAD_MAX_COST", "LIMIT_EXCEEDS_CAP" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`CLUSTER_NOT_UPGRADED`; `NO_PRICE_TABLE`; `STILL_RUNNING`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CLUSTER_NOT_UPGRADED", "NO_PRICE_TABLE", "STILL_RUNNING" ] }, "410": { "description": "`OUTPUT_EXPIRED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OUTPUT_EXPIRED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`TOO_MANY_PIPELINE_RUNS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_MANY_PIPELINE_RUNS" ] } } } }, "/apps/{app}/pipelines/{name}/estimate": { "post": { "operationId": "pipelines_estimate_run", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Estimate a pipeline run", "description": "The owner and the organization's members. Runs, fuel and cost of a run of a pipeline the app's release registers, for `inputs` (file ids, only counted) or `counts`, not both; numbers as decimal strings.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inputs": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "counts": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 } }, "params": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "steps": { "type": "object", "additionalProperties": { "type": "object", "properties": { "runs": { "type": "string" }, "fuel": { "type": "string" }, "cost": { "type": "string" } }, "required": [ "runs", "fuel" ] } }, "fuel": { "type": "string" }, "cost": { "type": "string" }, "priceVersion": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "steps", "fuel" ] } } } }, "400": { "description": "`BAD_INPUTS`; `BAD_PARAMS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_INPUTS", "BAD_PARAMS" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see; `NO_SUCH_PIPELINE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND", "NO_SUCH_PIPELINE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/pipelines/{name}/runs": { "post": { "operationId": "pipelines_start", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Start a pipeline run", "description": "The owner and the organization's members. Starts a run of a pipeline the app's release registers. `maxCost` (micro-units, a decimal string) caps the run, and `worstCase` answers it. `202`.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inputs": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "params": { "type": "object", "additionalProperties": true }, "maxCost": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "type": "string" }, "worstCase": { "type": "string" } }, "required": [ "run" ] } } } }, "400": { "description": "`BAD_INPUTS`; `BAD_MAX_COST`; `BAD_PARAMS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_INPUTS", "BAD_MAX_COST", "BAD_PARAMS" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see; `NO_SUCH_PIPELINE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND", "NO_SUCH_PIPELINE" ] }, "409": { "description": "`CLUSTER_NOT_UPGRADED`; `NO_PRICE_TABLE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CLUSTER_NOT_UPGRADED", "NO_PRICE_TABLE" ] }, "410": { "description": "`OUTPUT_EXPIRED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OUTPUT_EXPIRED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "422": { "description": "`PIPELINES_NEED_ONE_SERVICE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "PIPELINES_NEED_ONE_SERVICE" ] }, "429": { "description": "`TOO_MANY_PIPELINE_RUNS`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_MANY_PIPELINE_RUNS" ] } } } }, "/apps/{app}/presence": { "get": { "operationId": "presence_get", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Who is present", "description": "One entry per present device (a session's passkey, or an API key): its account, device and state (hex).\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "present": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "device": { "type": "string" }, "state": { "type": [ "string", "null" ] } }, "required": [ "account", "device", "state" ] } } }, "required": [ "present" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "post": { "operationId": "presence_publish", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Publish presence", "description": "The caller's presence state (hex), in sequence; not logged. A `null` (or absent) `state` retracts it.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seq": { "type": "integer", "format": "int64", "minimum": 0 }, "state": { "type": [ "string", "null" ] } }, "required": [ "seq" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`BAD_STATE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_STATE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/presence/stream": { "get": { "operationId": "presence_stream", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Presence as server-sent events", "description": "**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-sent events: a `snapshot`, then `presence` diffs.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/runs": { "get": { "operationId": "app_runs", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "An app's compute runs", "description": "Newest first, `limit` (1 to 100, default 20) at a time; `next` is the `before` of the next page, `null` on the last.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "next": { "type": [ "string", "null" ] } }, "required": [ "runs", "next" ] } } } }, "400": { "description": "`BAD_CURSOR`; `BAD_LIMIT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_CURSOR", "BAD_LIMIT" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/runs/{run}": { "get": { "operationId": "app_run", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "One compute run", "description": "Its record without arguments or keys: method, state, `cancelRequested`, `startTsMs`, attempts, input and output ids (sizes and SHA-256 only for callers who may list the app's files), usage, and `progress` as the leader last polled it.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/runs/{run}/logs": { "get": { "operationId": "app_run_logs", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "A compute run's attempt logs", "description": "Each attempt's module log, as a sealed file of the app: `{ attempt, id, size, sha256 }`. Only for those who may handle the app's files; the bytes are a files export.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "format": "int64", "minimum": 0 }, "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string" } }, "required": [ "attempt", "id", "size", "sha256" ] } } }, "required": [ "logs" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/storage": { "get": { "operationId": "app_storage", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "What an app stores", "description": "Keys, bytes and blobs held, and `lastWriteAt` (Unix seconds of its last committed write, `null` before one).\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "integer", "format": "int64", "minimum": 0 }, "bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "blobs": { "type": "integer", "format": "int64", "minimum": 0 }, "blobBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "lastWriteAt": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, "required": [ "keys", "bytes", "blobs", "blobBytes" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/transfer": { "post": { "operationId": "app_transfer", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Hand an app to another account", "description": "The owner (for an organization's app, while a member and in the app's team), or an organization admin; an organization's app only to a member. Answers `null`.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "to" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/upgrade": { "post": { "operationId": "app_upgrade", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Upgrade an app instance", "description": "To a release (`version`, of the app's own package unless `package` names another) or a `bundle`, code only: the state stays and is read by the new code. Whoever the package's manifest names (`upgrades`: the owner, or its publisher's `MANAGE_APPLICATION` holders), with a step-up over `{ bundle, migrate, manifest }`; an upgrade key signs in place of it. A refused or failed upgrade leaves the app on its release and answers `422 UPGRADE_FAILED` with the app log's error in `details` (`MigrationsNotSupported` when `migrate` is named: there are no migrations in this version). `error` is the app log's error value (`null` when it ran), free-form: the app's own.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" }, "service": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" }, "migrate": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "status": { "type": "string" }, "error": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "compute": { "type": "boolean" } }, "required": [ "index", "status", "error", "compute" ] } } } }, "400": { "description": "`AMBIGUOUS_COMPUTE`; `BAD_BUNDLE`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `VERSION_REQUIRED`. `details` of `BAD_BUNDLE`: a `ServiceRefused`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "AMBIGUOUS_COMPUTE", "BAD_BUNDLE", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "VERSION_REQUIRED" ], "x-calimero-details": { "BAD_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`CONFLICT`: the state does not allow it now; `RELEASE_DEADLINE`; `RUNTIME_TOO_OLD`. `details` of `RELEASE_DEADLINE`: a `ReleaseDeadline`, `RUNTIME_TOO_OLD`: a `RuntimeTooOld`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFLICT", "RELEASE_DEADLINE", "RUNTIME_TOO_OLD" ], "x-calimero-details": { "RELEASE_DEADLINE": { "$ref": "#/components/schemas/ReleaseDeadline" }, "RUNTIME_TOO_OLD": { "$ref": "#/components/schemas/RuntimeTooOld" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "422": { "description": "`UPGRADE_FAILED`. `details` of `UPGRADE_FAILED`: a `Applied`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UPGRADE_FAILED" ], "x-calimero-details": { "UPGRADE_FAILED": { "$ref": "#/components/schemas/Applied" } } } } } }, "/apps/{app}/usage": { "get": { "operationId": "app_usage", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "An app's runs per day", "description": "The owner or an organization admin: `today` and the 30 `days` before it, figures as decimal strings; `wallMs` is information only.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "today": { "$ref": "#/components/schemas/UsageDay" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDay" } } }, "required": [ "today", "days" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/apps/{app}/views": { "post": { "operationId": "views", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Read with a view method", "description": "Read linearizably (`consistency: \"strong\"`, the default; any value but `\"stale\"` reads as it): the replica answering waits until it applied the index the app's leader names once it confirmed it leads, and sends the view to the leader if it cannot catch up; or (`\"stale\"`) on the replica answering, as it stands; `minIndex` waits until the replica applied it (`503 NOT_CAUGHT_UP`). `args`, `result` and each event's `data` are the app's own JSON, free-form here: the app's ABI (`GET /apps/{app}/abi`, or its OpenAPI document) types them.\n\n**Who:** whoever the app's access admits (a public app: anyone).", "security": [ { "session": [] }, { "apiKey": [] }, {} ], "x-calimero-who": "whoever the app's access admits (a public app: anyone)", "x-calimero-sealed": true, "x-calimero-retry-safe": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "args": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "consistency": { "type": "string", "enum": [ "strong", "stale" ] }, "minIndex": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "method" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "result": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "receipt": { "$ref": "#/components/schemas/Receipt" } }, "required": [ "index", "result", "receipt" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "422": { "description": "`APP_ERROR`; `TRAP`. `details` of `APP_ERROR`: a `AppError`, `TRAP`: a `Trap`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "APP_ERROR", "TRAP" ], "x-calimero-details": { "APP_ERROR": { "$ref": "#/components/schemas/AppError" }, "TRAP": { "$ref": "#/components/schemas/Trap" } } }, "503": { "description": "`NOT_CAUGHT_UP`; `TIMEOUT`. `details` of `TIMEOUT`: a `RetryAfter`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_CAUGHT_UP", "TIMEOUT" ], "x-calimero-details": { "TIMEOUT": { "$ref": "#/components/schemas/RetryAfter" } } } } } }, "/apps/{app}/xcalls": { "get": { "operationId": "app_xcalls", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "An app's cross-app calls", "description": "The owner or an organization admin: how many calls wait in its outbox for delivery (`pending`, a count), and its dead letters, oldest first (`atMs`: the entry time it was dead-lettered at, Unix milliseconds).\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "integer", "format": "int64", "minimum": 0 }, "deadLetters": { "type": "array", "items": { "$ref": "#/components/schemas/DeadLetter" } } }, "required": [ "pending", "deadLetters" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "503": { "description": "`UNAVAILABLE`: the cluster cannot answer now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAVAILABLE" ] } } } }, "/attestation": { "get": { "operationId": "attestation", "tags": [ "Public" ], "x-calimero-group": "public", "summary": "The node's attestation", "description": "In the clear. A TDX quote binding the node's transport key (or, with `purpose=receipts`, its receipt key and the governance; with `purpose=kms`, what it verified of its KMS; with `purpose=orchestrator`, the cluster identity this replica holds) to `nonce`; `app`/`appHash` bind an app's bundle hash. A client checks it before it seals anything to the key.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": false, "parameters": [ { "name": "nonce", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "app", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "appHash", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "purpose", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "receipts", "kms", "orchestrator" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestationDoc" } } } }, "400": { "description": "`BAD_HASH`; `BAD_NONCE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_HASH", "BAD_NONCE" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] } } } }, "/auth/account-proof": { "post": { "operationId": "account_proof_prove", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Prove the account to another party", "description": "A statement signed with this node's receipt key that the caller's passkey session asked to bind `nonce` for `audience`.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string" }, "audience": { "type": "string" } }, "required": [ "nonce", "audience" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountProof" } } } }, "400": { "description": "`BAD_AUDIENCE`; `BAD_NONCE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_AUDIENCE", "BAD_NONCE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/activity": { "get": { "operationId": "activity_list", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "What the account's passkeys did", "description": "Newest first, the last 100: sign-ins (`app`, `origin`) and approvals (`method`, `subject`); `after` keeps the entries after that Unix second.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "activity": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "integer", "format": "int64", "minimum": 0 }, "passkey": { "type": "string" }, "kind": { "type": "string", "enum": [ "signIn", "approval" ] }, "app": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "method": { "type": "string" }, "subject": { "type": "string" } }, "required": [ "at", "passkey", "kind" ] } } }, "required": [ "activity" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/aliases": { "get": { "operationId": "alias_list", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "The account's aliases", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "aliases": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "aliases" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/aliases/{alias}": { "get": { "operationId": "alias_get", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Resolve an alias", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "alias", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "alias": { "type": "string" }, "appId": { "type": "string" } }, "required": [ "alias", "appId" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "put": { "operationId": "alias_set", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Set an alias", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "alias", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "type": "string" } }, "required": [ "app" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "alias_delete", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Remove an alias", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "alias", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/apikeys": { "post": { "operationId": "apikey_create", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Make an API key", "description": "Scoped to `apps` and `methods`, read-only or not, for `ttlSecs`; `upgrades` makes an upgrade key, which signs upgrades of one app in place of a passkey. `412` first. The key is shown once.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "apps": { "type": "array", "items": { "type": "string" } }, "methods": { "type": "array", "items": { "type": "string" } }, "readOnly": { "type": "boolean" }, "allowConfirm": { "type": "boolean" }, "ttlSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "upgrades": { "type": "object", "properties": { "app": { "type": "string" }, "package": { "type": "string" } }, "required": [ "app" ] }, "confirm": { "$ref": "#/components/schemas/Confirm" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" }, "key": { "type": "string" } }, "required": [ "keyId", "key" ] } } } }, "400": { "description": "`BAD_UPGRADE_KEY`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_UPGRADE_KEY", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] } } }, "get": { "operationId": "apikey_list", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "The account's API keys", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "keys" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/apikeys/{key}": { "delete": { "operationId": "apikey_revoke", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Revoke an API key", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/apps": { "get": { "operationId": "account_apps", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "The account's own apps", "description": "The apps the account owns, in any organization (a package-bound session: its package's), with its personal organization's `approvedReleases`: each app's release, the newer releases it may upgrade to, its last upgrade, its replicas' releases and `lastWriteAt`.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/AppScope" }, "governance": { "$ref": "#/components/schemas/Governance" }, "approvedReleases": { "type": [ "array", "null" ], "items": { "type": "string" } }, "clusterReleases": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterRelease" } }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/ReportApp" } }, "next": { "type": [ "string", "null" ] } }, "required": [ "scope", "governance", "approvedReleases", "clusterReleases", "apps", "next" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/backup-key": { "get": { "operationId": "account_backup_key", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "The account's backup key", "description": "The X25519 public key the recovery-disk backups of the account's personal apps are sealed to (`key`, `null` while none is set).\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeyAnswer" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "post": { "operationId": "account_set_backup_key", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Set the account's backup key", "description": "`publicKey`: 64 lowercase hex, an X25519 public key whose private half the account holder keeps (never a node), for its personal apps, where owners upgrade apps. `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "publicKey" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeyAnswer" } } } }, "400": { "description": "`BAD_BACKUP_KEY`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BACKUP_KEY", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/logout": { "post": { "operationId": "logout", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "End this session", "description": "**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/logout-all": { "post": { "operationId": "logout_all", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "End every session of the account", "description": "`revoked`: how many sessions ended.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "revoked" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/me": { "get": { "operationId": "me", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "The caller's account", "description": "The account, its passkeys (with `addedAt` and `lastSignInAt`), organizations (`personal`: the one made at sign-up, where its instances go unless they name another; its approvals are that organization's), recovery state, and how the caller came (`via`).\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "name": { "type": "string" }, "passkeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "signCount": { "type": "integer", "format": "int64", "minimum": 0 }, "label": { "type": [ "string", "null" ] }, "addedAt": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "lastSignInAt": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, "required": [ "id", "signCount", "label" ] } }, "orgs": { "type": "array", "items": { "type": "object", "properties": { "orgId": { "type": "string" }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/OrgRole" }, "personal": { "type": "boolean" } }, "required": [ "orgId", "name", "role" ] } }, "via": { "type": "string", "enum": [ "session", "apiKey" ] }, "passkeyId": { "type": [ "string", "null" ] }, "app": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "recoveryCode": { "type": "boolean" }, "recoveryPending": { "type": [ "object", "null" ], "properties": { "accountId": { "type": "string" }, "credentialId": { "type": "string" }, "startedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "readyAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "accountId", "credentialId", "startedAt", "readyAt" ] } }, "required": [ "accountId", "name", "passkeys", "orgs", "via", "passkeyId" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/passkey/login/begin": { "post": { "operationId": "login_begin", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Start a sign-in", "description": "A WebAuthn challenge for any passkey of the cluster. `origin` is an app frontend's registered origin, whose rp-id the ceremony then uses. `options` are the WebAuthn options to hand to the browser as they are: free-form here, their shape is WebAuthn's.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin": { "type": "string" } } } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "options": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "challengeId", "options" ] } } } }, "429": { "description": "`RATE_LIMITED`: a node's limit on open streams or ceremonies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RATE_LIMITED" ] } } } }, "/auth/passkey/login/finish": { "post": { "operationId": "login_finish", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Finish a sign-in", "description": "**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "assertion": { "$ref": "#/components/schemas/Assertion" } }, "required": [ "challengeId", "assertion" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`PASSKEY_UNKNOWN_HERE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "PASSKEY_UNKNOWN_HERE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/passkey/register/begin": { "post": { "operationId": "register_begin", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Start a sign-up", "description": "Creation options for a new passkey. `invite` is an organization or cluster sign-up invite token, which the policy may require; `403 SIGN_UP_REFUSED` when the policy would refuse the sign-up. `options` are the WebAuthn options to hand to the browser as they are: free-form here, their shape is WebAuthn's.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "origin": { "type": "string" }, "invite": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "options": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "challengeId", "options" ] } } } }, "403": { "description": "`SIGN_UP_REFUSED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "SIGN_UP_REFUSED" ] }, "429": { "description": "`RATE_LIMITED`: a node's limit on open streams or ceremonies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RATE_LIMITED" ] } } } }, "/auth/passkey/register/finish": { "post": { "operationId": "register_finish", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Finish a sign-up", "description": "The new passkey's registration. Answers `412 CONFIRM_REQUIRED` first: the new passkey signs the account it creates; the retry with `confirm` (and the same `invite`) opens a session, and redeems `invite` for the new account.\n\n**Who:** anyone. **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "preferred", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "registration": { "$ref": "#/components/schemas/Registration" }, "invite": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "challengeId", "registration" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "`BAD_REGISTRATION`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REGISTRATION", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`PASSKEY_UNKNOWN_HERE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "PASSKEY_UNKNOWN_HERE" ] }, "403": { "description": "`SIGN_UP_REFUSED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "SIGN_UP_REFUSED" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/passkeys/add/begin": { "post": { "operationId": "passkey_add_begin", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Start adding a passkey", "description": "Creation options for another passkey (a device) on the caller's account. `options` are the WebAuthn options to hand to the browser as they are: free-form here, their shape is WebAuthn's.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "options": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "challengeId", "options" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/passkeys/add/finish": { "post": { "operationId": "passkey_add_finish", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Finish adding a passkey", "description": "Answers `412` first; sent again with `confirm` signed by a passkey the account already has.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "registration": { "$ref": "#/components/schemas/Registration" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "challengeId", "registration" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentialId": { "type": "string" } }, "required": [ "credentialId" ] } } } }, "400": { "description": "`BAD_REGISTRATION`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REGISTRATION", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/passkeys/{cred}": { "post": { "operationId": "passkey_label", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Name a passkey", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "cred", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } }, "required": [ "label" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "passkey_remove", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Remove a passkey", "description": "Its sessions end. `412` first; the retry's JSON body is `{ confirm }`.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "cred", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/recovery": { "post": { "operationId": "recovery_create", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Make a recovery code", "description": "Shown once, replacing any; `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "recovery_remove", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Remove the recovery code", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/recovery/begin": { "post": { "operationId": "account_recovery_begin", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Start an account recovery", "description": "Signed out, with the recovery code: creation options for the passkey that will replace the lost ones. `options` are the WebAuthn options to hand to the browser as they are: free-form here, their shape is WebAuthn's.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "options": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "challengeId", "options" ] } } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`RATE_LIMITED`: a node's limit on open streams or ceremonies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RATE_LIMITED" ] } } } }, "/auth/recovery/cancel": { "post": { "operationId": "account_recovery_cancel", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Cancel an account recovery", "description": "With a passkey the account has; `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/recovery/finish": { "post": { "operationId": "account_recovery_finish", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Finish an account recovery", "description": "Approved by the new passkey once `readyAt` passed (`412` first): adds it and ends every session of the account.\n\n**Who:** anyone. **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "409": { "description": "`RECOVERY_NOT_READY`. `details` of `RECOVERY_NOT_READY`: a `RecoveryNotReady`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RECOVERY_NOT_READY" ], "x-calimero-details": { "RECOVERY_NOT_READY": { "$ref": "#/components/schemas/RecoveryNotReady" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/recovery/start": { "post": { "operationId": "account_recovery_start", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Spend the recovery code", "description": "Logs the new passkey as pending; it may finish the recovery once `readyAt` passed (72 h). `401` for a wrong or spent code.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string" }, "code": { "type": "string" }, "registration": { "$ref": "#/components/schemas/Registration" } }, "required": [ "challengeId", "code", "registration" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string" }, "credentialId": { "type": "string" }, "startedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "readyAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "accountId", "credentialId", "startedAt", "readyAt" ] } } } }, "400": { "description": "`BAD_REGISTRATION`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REGISTRATION", "WRONG_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "409": { "description": "`RECOVERY_PENDING`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RECOVERY_PENDING" ] } } } }, "/auth/refresh": { "post": { "operationId": "refresh", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "Refresh a session", "description": "A new session and the refresh token to use next (the same one until it is an hour old). A reused, superseded token ends the sessions it opened.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string" } }, "required": [ "refreshToken" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "503": { "description": "`UNAVAILABLE`: the cluster cannot answer now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAVAILABLE" ] } } } }, "/auth/sessions": { "get": { "operationId": "sessions_list", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "The account's live sessions", "description": "Latest active first, at most 256. `openedAt` (Unix seconds) is `null` for a session opened before the node kept it.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "session": { "type": "string" }, "passkey": { "type": [ "string", "null" ] }, "app": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "openedAt": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "lastActiveAt": { "type": "integer", "format": "int64", "minimum": 0 }, "current": { "type": "boolean" } }, "required": [ "session", "passkey", "app", "origin", "openedAt", "lastActiveAt", "current" ] } } }, "required": [ "sessions" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/sessions/{session}": { "delete": { "operationId": "session_revoke", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "End one session", "description": "`404` for a session the account does not hold live.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "session", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/auth/usage": { "get": { "operationId": "usage", "tags": [ "Accounts" ], "x-calimero-group": "auth", "summary": "The account's usage against its quotas", "description": "The apps the account owns, its bundle bytes (a decimal string), API keys and owned organizations; the file bytes held by each payer it belongs to (each organization it is in, and `account:` for its own apps); the cluster's quotas; and what today's runs of the apps the account develops used (decimal strings).\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "integer", "format": "int64", "minimum": 0 }, "bundleBytes": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "apiKeys": { "type": "integer", "format": "int64", "minimum": 0 }, "orgsOwned": { "type": "integer", "format": "int64", "minimum": 0 }, "fileBytes": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 } }, "quotas": { "$ref": "#/components/schemas/Quotas" }, "developerFuelToday": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "developerWritesToday": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" } }, "required": [ "apps", "bundleBytes", "apiKeys", "orgsOwned", "fileBytes", "quotas", "developerFuelToday", "developerWritesToday" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/bundles": { "post": { "operationId": "bundle_put", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Upload a raw component", "description": "A `calimero:app` component, 16 MiB at most; only on a node started with `--allow-unsigned-bundles` or `--dev`. A WASM core module (SDK 0.12) is refused `400 UNSUPPORTED_BUNDLE`.\n\n**Who:** an installer (an account holder, or an unscoped API key that is not read-only).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "an installer (an account holder, or an unscoped API key that is not read-only)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/wasm": { "schema": { "type": "string", "format": "binary", "contentMediaType": "application/wasm" } } }, "description": "the component" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "hash": { "type": "string" } }, "required": [ "hash" ] } } } }, "400": { "description": "`BAD_BUNDLE`; `UNSUPPORTED_BUNDLE`. `details` of `BAD_BUNDLE`: a `ServiceRefused`, `UNSUPPORTED_BUNDLE`: a `ServiceRefused`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BUNDLE", "UNSUPPORTED_BUNDLE" ], "x-calimero-details": { "BAD_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" }, "UNSUPPORTED_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] } } } }, "/consent/requests": { "post": { "operationId": "consent_page_create", "tags": [ "Consent" ], "x-calimero-group": "consent", "summary": "Ask the account's owner to approve", "description": "From an app's frontend: a release approval, an upgrade of its instance, outbound prefixes, a new organization, a new invite or joining with one, leaving an organization, a member's removal, role, teams or capabilities, an invite's revocation, an organization's name, its deletion, defaults or all-apps grants, approved on the node's own consent page (`url`), which takes the passkey. What the approval made (`orgId`, an invite's `token`, the `org` joined, a rename's `{ orgId, name }`, a deletion's `apps`) is in `/consent/{request}/result`'s `outcome`. 64 KiB at most.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "release" ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "account" ] }, { "type": "object", "properties": { "org": { "type": "string" } }, "required": [ "org" ] } ] }, "subject": { "type": "object", "properties": { "version": { "type": "string" }, "withdraw": { "type": "boolean" } }, "required": [ "version" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "scope", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "upgrade" ] }, "subject": { "type": "object", "properties": { "app": { "type": "string" }, "toVersion": { "type": "string" } }, "required": [ "app", "toVersion" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "outbound" ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "account" ] }, { "type": "object", "properties": { "org": { "type": "string" } }, "required": [ "org" ] } ] }, "subject": { "type": "object", "properties": { "package": { "type": "string" }, "prefixes": { "type": "array", "items": { "type": "string" } } } }, "returnTo": { "type": "string" } }, "required": [ "kind", "scope", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "createOrg" ] }, "subject": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "createInvite" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "role": { "type": "string", "enum": [ "guest", "member", "admin" ] }, "teams": { "type": "array", "items": { "type": "string" } }, "ttlSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "uses": { "type": "integer", "format": "int64", "minimum": 0 }, "allApps": { "type": "boolean" } }, "required": [ "org", "role" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acceptInvite" ] }, "subject": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "leaveOrg" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" } }, "required": [ "org" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "removeMember" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "account": { "type": "string" } }, "required": [ "org", "account" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "setMemberRole" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "account": { "type": "string" }, "role": { "type": "string", "enum": [ "guest", "member", "admin", "owner" ] } }, "required": [ "org", "account", "role" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "setMemberTeams" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "account": { "type": "string" }, "teams": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "string" }, "role": { "type": "string", "enum": [ "lead", "member", "readOnly" ] }, "capabilities": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "team" ] } } }, "required": [ "org", "account", "teams" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "removeMemberTeams" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "account": { "type": "string" }, "teams": { "type": "array", "items": { "type": "string" } } }, "required": [ "org", "account", "teams" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "revokeInvite" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "inviteKey": { "type": "string" } }, "required": [ "org", "inviteKey" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "renameOrg" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "name": { "type": "string" } }, "required": [ "org", "name" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deleteOrg" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" } }, "required": [ "org" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "setCapabilities" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "account": { "type": "string" }, "team": { "type": "string" }, "capabilities": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "org", "capabilities" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "setAllApps" ] }, "subject": { "type": "object", "properties": { "org": { "type": "string" }, "account": { "type": "string" }, "allApps": { "type": "boolean" } }, "required": [ "org", "account", "allApps" ] }, "returnTo": { "type": "string" } }, "required": [ "kind", "subject", "returnTo" ], "additionalProperties": false } ], "discriminator": { "propertyName": "kind" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "url": { "type": "string" }, "code": { "type": "string" }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "requestId", "url", "code", "expiresAt" ] } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/consent/{request}/result": { "get": { "operationId": "consent_page_result", "tags": [ "Consent" ], "x-calimero-group": "consent", "summary": "What became of a consent request", "description": "`decidedAt` (Unix seconds) is `null` while it is pending. `outcome`, once approved, is what the approval made: `{ orgId }` for `createOrg` (with `teamId`, the asking app's own team the organization starts with, when an app's frontend asked on a cluster that makes it), `{ token }` for `createInvite`, `{ org }` for `acceptInvite`, `{ orgId, name }` for `renameOrg`, `{ apps }` (the apps deleted) for `deleteOrg`; absent for the other kinds.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "parameters": [ { "name": "request", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "kind": { "type": "string", "enum": [ "release", "upgrade", "outbound", "createOrg", "createInvite", "acceptInvite", "leaveOrg", "removeMember", "setMemberRole", "setMemberTeams", "removeMemberTeams", "revokeInvite", "renameOrg", "deleteOrg", "setCapabilities", "setAllApps" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "declined" ] }, "decidedAt": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "outcome": { "type": "object", "properties": { "orgId": { "type": "string" }, "teamId": { "type": "string" }, "token": { "type": "string" }, "org": { "type": "string" }, "name": { "type": "string" }, "apps": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "requestId", "kind", "status", "decidedAt" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "503": { "description": "`UNAVAILABLE`: the cluster cannot answer now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAVAILABLE" ] } } } }, "/deployers": { "post": { "operationId": "deployer_grant", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Grant a deployer", "description": "The cluster's owner, with a passkey.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deployer": { "$ref": "#/components/schemas/Deployer" }, "until": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "deployer" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "deployer": { "$ref": "#/components/schemas/Deployer" }, "grant": { "$ref": "#/components/schemas/DeployerGrant" } }, "required": [ "key", "deployer", "grant" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "get": { "operationId": "deployer_list", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "The deployers", "description": "The operator, or the cluster's owner: the deployments and deployers governance, the owner (`null` until named), and every grant (`until` RFC 3339 and `untilSecs`, `null` for none; `grantedAt` RFC 3339; `deployer` `null` for a key it cannot read).\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployments": { "type": "string", "enum": [ "open", "granted" ] }, "deployers": { "type": "string", "enum": [ "operator", "owner" ] }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/Deployer" }, { "type": "null" } ] }, "grants": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "deployer": { "anyOf": [ { "$ref": "#/components/schemas/Deployer" }, { "type": "null" } ] }, "until": { "type": [ "string", "null" ] }, "untilSecs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "grantedAt": { "type": "string" }, "grantedBy": { "type": "string" } }, "required": [ "key", "deployer", "until", "untilSecs", "grantedAt", "grantedBy" ] } } }, "required": [ "deployments", "deployers", "owner", "grants" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/deployers/{key}": { "delete": { "operationId": "deployer_revoke", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Revoke a deployer", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/deployments": { "post": { "operationId": "deployment_create", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Create a deployment", "description": "A named set of releases an owner (an account or organization) offers for others to instantiate. Answers its id, the record as made (no apps yet) and its frontend host (`null` on a node with no apps domain).\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "owner": { "$ref": "#/components/schemas/Deployer" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "name", "owner" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "deployment": { "$ref": "#/components/schemas/DeploymentRecord" }, "host": { "type": [ "string", "null" ] } }, "required": [ "id", "deployment", "host" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "get": { "operationId": "deployment_list", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Deployments", "description": "The deployments the caller manages.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/Deployment" } } }, "required": [ "deployments" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/deployments/{id}": { "get": { "operationId": "deployment_get", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "One deployment", "description": "As anyone may read it: its name, its owner's kind and name (`null` when unknown), and the releases it offers; never its managers or customers.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "host": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "owner": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "account", "org" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "name" ] }, "apps": { "type": "array", "items": { "type": "object", "properties": { "app": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" } }, "required": [ "app", "package", "version" ] } } }, "required": [ "id", "host", "name", "owner", "apps" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "deployment_delete", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Delete a deployment", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "type": "string" } }, "required": [ "deployment" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/deployments/{id}/apps": { "post": { "operationId": "deployment_offer", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Offer a release in a deployment", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "app", "package", "version" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "type": "string" }, "app": { "type": "string" } }, "required": [ "deployment", "app" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/deployments/{id}/apps/{app}": { "delete": { "operationId": "deployment_withdraw", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Withdraw an offer", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "type": "string" }, "app": { "type": "string" } }, "required": [ "deployment", "app" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/deployments/{id}/orgs": { "get": { "operationId": "deployment_orgs", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "The organizations a deployment serves", "description": "For its managers: each organization with instances from it, its name (`null` when unknown), member counts (`activeMembers30d`: active in the last 30 days), its instances and the releases they run, and when its first was created (RFC 3339); instances outside an organization, or in a personal organization, are only counted (`outsideOrgs`). Never who the members are.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deployment": { "type": "string" }, "orgs": { "type": "array", "items": { "type": "object", "properties": { "orgId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "memberCount": { "type": "integer", "format": "int64", "minimum": 0 }, "activeMembers30d": { "type": "integer", "format": "int64", "minimum": 0 }, "instances": { "type": "integer", "format": "int64", "minimum": 0 }, "apps": { "type": "array", "items": { "type": "object", "properties": { "app": { "type": "string" }, "version": { "type": "string" } }, "required": [ "app", "version" ] } }, "firstCreatedAt": { "type": "string" } }, "required": [ "orgId", "name", "memberCount", "activeMembers30d", "instances", "apps", "firstCreatedAt" ] } }, "outsideOrgs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "deployment", "orgs", "outsideOrgs" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/health": { "get": { "operationId": "health", "tags": [ "Public" ], "x-calimero-group": "public", "summary": "Node health", "description": "In the clear. The node's id, the system group's leader (`null`: none known), its `merod` release, the newest cluster version it supports (`clusterVersion`) and the cluster's rollback epoch (`null` on a node without a rollback counter).\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": false, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "node": { "type": "integer", "format": "int64", "minimum": 0 }, "systemLeader": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "release": { "type": "string" }, "clusterVersion": { "type": "string" }, "rollbackEpoch": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, "required": [ "ok", "node", "systemLeader", "release", "clusterVersion", "rollbackEpoch" ] } } } } } } }, "/invites/{token}/redeem": { "post": { "operationId": "invite_redeem", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Join with an invite", "description": "No passkey prompt: the node signs the redemption with the token's key. Answers the organization joined.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "org": { "type": "string" } }, "required": [ "org" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/ops/apps": { "get": { "operationId": "ops_apps", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "What each app runs", "description": "Each app's bundle, package, publisher, who holds its upgrades and release approvals, its last upgrade, approved releases, replicas' releases and `lastWriteAt`.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fresh": { "type": "boolean" }, "governance": { "$ref": "#/components/schemas/Governance" }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/ReportApp" } }, "next": { "type": [ "string", "null" ] } }, "required": [ "fresh", "governance", "apps", "next" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/apps/{app}/replicas": { "post": { "operationId": "ops_set_replicas", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Move an app's replicas", "description": "Signed over ` / __set_replicas / { replicas }` (sorted); at least `min(3, nodes)` registered nodes, each on a release the app's owner approved. The set it already has answers `unchanged: true`. `status` is the app group's Raft status when the move finished (as the leader saw it).\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "replicas": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "replicas" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "group": { "type": "integer", "format": "int64", "minimum": 0 }, "leader": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "is_leader": { "type": "boolean" }, "term": { "type": "integer", "format": "int64", "minimum": 0 }, "last_log": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "applied": { "type": "integer", "format": "int64", "minimum": 0 }, "voters": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "learners": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } } }, "required": [ "group", "leader", "is_leader", "term", "last_log", "applied", "voters", "learners" ] }, "unchanged": { "type": "boolean" } }, "required": [ "status", "unchanged" ] } } } }, "400": { "description": "`DUPLICATE_REPLICA`; `JOB_NODE`; `TOO_FEW`; `UNKNOWN_NODE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "DUPLICATE_REPLICA", "JOB_NODE", "TOO_FEW", "UNKNOWN_NODE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`MOVE_IN_PROGRESS`; `RUNTIME_TOO_OLD`. `details` of `RUNTIME_TOO_OLD`: a `RuntimeTooOld`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "MOVE_IN_PROGRESS", "RUNTIME_TOO_OLD" ], "x-calimero-details": { "RUNTIME_TOO_OLD": { "$ref": "#/components/schemas/RuntimeTooOld" } } }, "421": { "description": "`NOT_LEADER`: send it to the leader named in `details.leaderUrl`. `details` of `NOT_LEADER`: a `NotLeader`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_LEADER" ], "x-calimero-details": { "NOT_LEADER": { "$ref": "#/components/schemas/NotLeader" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/apps/{app}/restore": { "post": { "operationId": "ops_restore", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Restore an app from its sealed backup", "description": "Signed over ` / __restore_app / { backup, sha256 }`. The receiving node holds the backup (`backup`, else the newest, in `{backup-dir}/{app}/`) and seeds the restore; answers once every replica holds the restored state: the rows restored, the backup (`format` 0, with `merod` and `release` `null`, for one written before manifests) and the app group's Raft status. `recovery` restores from a recovery-disk file instead (in the app's holder's directory under `--recover-from`, else `--recovery-dir`), opened with the data key its holder opened from it (hex); `backup` is then the file's name and `sha256` its body's.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "backup": { "type": "string" }, "recovery": { "type": "object", "properties": { "file": { "type": "string" }, "key": { "type": "string" } }, "required": [ "file", "key" ] }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "type": "string" }, "group": { "type": "integer", "format": "int64", "minimum": 0 }, "rows": { "type": "integer", "format": "int64", "minimum": 0 }, "backup": { "type": "object", "properties": { "name": { "type": "string" }, "index": { "type": "integer", "format": "int64", "minimum": 0 }, "format": { "type": "integer", "format": "int64", "minimum": 0 }, "merod": { "type": [ "string", "null" ] }, "release": { "type": [ "string", "null" ] } }, "required": [ "name", "index", "format", "merod", "release" ] }, "status": { "$ref": "#/components/schemas/GroupStatus" } }, "required": [ "app", "group", "rows", "backup", "status" ] } } } }, "400": { "description": "`BAD_BACKUP`; `BAD_RECOVERY_FILE`; `BAD_RECOVERY_KEY`; `BAD_REQUEST`: the request is malformed; `NOT_A_REPLICA_NODE`; `UNATTESTED_RECOVERY_FILE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BACKUP", "BAD_RECOVERY_FILE", "BAD_RECOVERY_KEY", "BAD_REQUEST", "NOT_A_REPLICA_NODE", "UNATTESTED_RECOVERY_FILE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "404": { "description": "`BACKUP_NOT_FOUND`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BACKUP_NOT_FOUND" ] }, "409": { "description": "`BACKUP_FROM_NEWER_RELEASE`; `BUNDLE_GONE`; `MOVE_IN_PROGRESS`; `NO_BACKUP_DIR`; `RECOVERY_SEGMENTS_MISSING`; `UNKNOWN_BACKUP_FORMAT`; `UPGRADE_PENDING`. `details` of `UPGRADE_PENDING`: a `UpgradePending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BACKUP_FROM_NEWER_RELEASE", "BUNDLE_GONE", "MOVE_IN_PROGRESS", "NO_BACKUP_DIR", "RECOVERY_SEGMENTS_MISSING", "UNKNOWN_BACKUP_FORMAT", "UPGRADE_PENDING" ], "x-calimero-details": { "UPGRADE_PENDING": { "$ref": "#/components/schemas/UpgradePending" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/apps/{app}/upgrade": { "post": { "operationId": "ops_upgrade", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Upgrade an app as the operator", "description": "To a release the operator installed, where the operator holds app upgrades. `error` is the app log's error value (`null` when it ran), free-form: the app's own.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "app", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" }, "service": { "type": "string" }, "migrate": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "status": { "type": "string" }, "error": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "compute": { "type": "boolean" } }, "required": [ "index", "status", "error", "compute" ] } } } }, "400": { "description": "`AMBIGUOUS_COMPUTE`; `BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "AMBIGUOUS_COMPUTE", "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`NOT_INSTALLED`; `RELEASE_DEADLINE`; `RUNTIME_TOO_OLD`. `details` of `RELEASE_DEADLINE`: a `ReleaseDeadline`, `RUNTIME_TOO_OLD`: a `RuntimeTooOld`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_INSTALLED", "RELEASE_DEADLINE", "RUNTIME_TOO_OLD" ], "x-calimero-details": { "RELEASE_DEADLINE": { "$ref": "#/components/schemas/ReleaseDeadline" }, "RUNTIME_TOO_OLD": { "$ref": "#/components/schemas/RuntimeTooOld" } } }, "422": { "description": "`UPGRADE_FAILED`. `details` of `UPGRADE_FAILED`: a `Applied`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UPGRADE_FAILED" ], "x-calimero-details": { "UPGRADE_FAILED": { "$ref": "#/components/schemas/Applied" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/backup": { "post": { "operationId": "ops_backup", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Snapshot the apps this node leads", "description": "Into `--backup-dir`. With `all=true`, every group this node holds, leader or not: what a node of a cluster that lost a majority still has, to found the cluster again from (`merod --bootstrap --restore-from`). `written`: how many snapshots it wrote.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "all", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "written": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "written" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/backup-key": { "get": { "operationId": "ops_backup_key", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "The operator's backup key", "description": "The X25519 public key every app's recovery-disk backups are sealed to where the operator upgrades apps (`key`, `null` while none is set).\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeyAnswer" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } }, "post": { "operationId": "ops_set_backup_key", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Set the operator's backup key", "description": "Signed over `operator / __set_backup_key / { publicKey }`, where the operator upgrades apps (else `403`). `publicKey`: 64 lowercase hex, an X25519 public key whose private half the operator keeps (never a node).\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "publicKey" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeyAnswer" } } } }, "400": { "description": "`BAD_BACKUP_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BACKUP_KEY" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/cluster": { "get": { "operationId": "ops_cluster", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "The cluster's identity", "description": "The cluster's name and the identity this replica holds (hex).\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cluster": { "type": "string" }, "identity": { "type": "string" } }, "required": [ "cluster", "identity" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/cluster-owner": { "post": { "operationId": "ops_cluster_owner", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Name the cluster's owner", "description": "The account or organization that then runs sign-up and deployers with passkeys; once.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "$ref": "#/components/schemas/Deployer" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "owner" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "$ref": "#/components/schemas/Deployer" } }, "required": [ "owner" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`CONFLICT`: the state does not allow it now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFLICT" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/deployers": { "post": { "operationId": "ops_deployer_grant", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Grant a deployer", "description": "An account or organization that may install where deployments are granted, `until` an RFC 3339 time.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deployer": { "$ref": "#/components/schemas/Deployer" }, "until": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "deployer" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "deployer": { "$ref": "#/components/schemas/Deployer" }, "grant": { "$ref": "#/components/schemas/DeployerGrant" } }, "required": [ "key", "deployer", "grant" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/deployers/{key}": { "delete": { "operationId": "ops_deployer_revoke_delete", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Revoke a deployer", "description": "**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/deployers/{key}/revoke": { "post": { "operationId": "ops_deployer_revoke_post", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Revoke a deployer (POST)", "description": "The same as the `DELETE`, for an HTTP client whose `DELETE` carries no body.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/deployments/granted": { "post": { "operationId": "ops_deployments_granted", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Require deployer grants", "description": "From now on only granted deployers install; once.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "governance": { "$ref": "#/components/schemas/Governance" } }, "required": [ "governance" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`CONFLICT`: the state does not allow it now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFLICT" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/job-nodes/{id}/attestation": { "get": { "operationId": "ops_job_node_attestation", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Whether the cluster accepts a job node", "description": "Runs the check the leader makes before it sends a job node work: a quote that passes the release policy, this cluster and node, this cluster's identity, a release not retired (not the per-app release approval). `admitted` carries the attested `release`; `refused` (final), with the reason: a 400 or 404 from the node, a 2xx that is oversized or does not decode, a failed verification, or a 400 or 404 from the collateral source on the PCK certificate or TCB info request; `unreachable` (transient), with the reason: anything else, including no answer, any other status from the node and any other collateral failure. `503` when this node's directory is stale. A verified answer is reused for up to a minute.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "admitted" ] }, "node": { "type": "integer", "format": "int64", "minimum": 0 }, "release": { "type": "string" } }, "required": [ "state", "node", "release" ] }, { "type": "object", "properties": { "state": { "type": "string", "enum": [ "refused", "unreachable" ] }, "node": { "type": "integer", "format": "int64", "minimum": 0 }, "reason": { "type": "string" } }, "required": [ "state", "node", "reason" ] } ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "503": { "description": "`UNAVAILABLE`: the cluster cannot answer now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAVAILABLE" ] } } } }, "/ops/metrics": { "get": { "operationId": "ops_metrics", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Prometheus metrics", "description": "Including per-app usage for billing. `--metrics-listen ADDR` also serves it as plain `GET /metrics` there.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK: the Prometheus text format.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/nodes": { "post": { "operationId": "ops_register_node", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Register a node", "description": "Signed with the operator key over `cluster / __register_node / { id, addr, zone }`. The system leader adds it as a learner and promotes caught-up learners while fewer than 3 voters are left; `role: job` registers a compute node (in `pool`).\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "minimum": 0 }, "addr": { "type": "string" }, "zone": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" }, "role": { "type": "string", "enum": [ "replica", "job" ] }, "pool": { "type": "string" } }, "required": [ "id", "addr" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`BAD_ADDRESS`; `BAD_POOL`; `NODE_HOLDS_CLUSTER`; `POOL_FOR_JOB_NODES`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_ADDRESS", "BAD_POOL", "NODE_HOLDS_CLUSTER", "POOL_FOR_JOB_NODES" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`ADDRESS_TAKEN`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "ADDRESS_TAKEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/nodes/{id}": { "delete": { "operationId": "ops_remove_node", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Remove a node", "description": "One no app keeps a replica on; the system leader (elsewhere `421 NOT_LEADER`); signed over `__remove_node / { id }`.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "group": { "type": "integer", "format": "int64", "minimum": 0 }, "leader": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "is_leader": { "type": "boolean" }, "term": { "type": "integer", "format": "int64", "minimum": 0 }, "last_log": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "applied": { "type": "integer", "format": "int64", "minimum": 0 }, "voters": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "learners": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } } }, "required": [ "group", "leader", "is_leader", "term", "last_log", "applied", "voters", "learners" ] } }, "required": [ "status" ] } } } }, "400": { "description": "`LAST_NODE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "LAST_NODE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "421": { "description": "`NOT_LEADER`: send it to the leader named in `details.leaderUrl`. `details` of `NOT_LEADER`: a `NotLeader`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_LEADER" ], "x-calimero-details": { "NOT_LEADER": { "$ref": "#/components/schemas/NotLeader" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/nodes/{id}/receipt-key": { "get": { "operationId": "ops_receipt_key", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "A node's receipt key", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "key": { "type": "string" }, "release": { "type": "string" }, "attestedAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "node", "key", "release", "attestedAt" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] } } } }, "/ops/orgs": { "get": { "operationId": "ops_orgs", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Each organization's approved releases", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fresh": { "type": "boolean" }, "governance": { "$ref": "#/components/schemas/Governance" }, "orgs": { "type": "array", "items": { "type": "object", "properties": { "org": { "type": "string" }, "approvedReleases": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "org", "approvedReleases" ] } }, "next": { "type": [ "string", "null" ] } }, "required": [ "fresh", "governance", "orgs", "next" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/orgs/{org}/upgrade": { "post": { "operationId": "ops_org_upgrade", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "An operator's upgrade run", "description": "**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "team": { "type": "string" }, "cascade": { "type": "boolean" }, "migrate": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "package", "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeRun" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/outbound": { "post": { "operationId": "ops_outbound", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Approve outbound prefixes", "description": "Where the operator holds outbound approvals.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "prefixes": { "$ref": "#/components/schemas/OutboundSelection" }, "replace": { "type": "boolean" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "package" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundApproved" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/packages": { "post": { "operationId": "ops_package_upload", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Install an uploaded release as the operator", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream" } } }, "description": "the `.mpk`" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "signerId": { "type": "string" }, "services": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "package", "version", "signerId", "services" ] } } } }, "400": { "description": "`BAD_BUNDLE`; `BAD_PACKAGE`; `COMPUTE_ABI_MISMATCH`; `UNSUPPORTED_BUNDLE`. `details` of `BAD_BUNDLE`: a `ServiceRefused`, `COMPUTE_ABI_MISMATCH`: a `ServiceRefused`, `UNSUPPORTED_BUNDLE`: a `ServiceRefused`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BUNDLE", "BAD_PACKAGE", "COMPUTE_ABI_MISMATCH", "UNSUPPORTED_BUNDLE" ], "x-calimero-details": { "BAD_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" }, "COMPUTE_ABI_MISMATCH": { "$ref": "#/components/schemas/ServiceRefused" }, "UNSUPPORTED_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } }, "get": { "operationId": "ops_package_list", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "The releases the operator installed", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } } }, "required": [ "packages" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/packages/install": { "post": { "operationId": "ops_package_install", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Install a release from the registry as the operator", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" } }, "required": [ "package", "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "signerId": { "type": "string" }, "services": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "package", "version", "signerId", "services" ] } } } }, "400": { "description": "`BAD_BUNDLE`; `COMPUTE_ABI_MISMATCH`; `UNSUPPORTED_BUNDLE`. `details` of `BAD_BUNDLE`: a `ServiceRefused`, `COMPUTE_ABI_MISMATCH`: a `ServiceRefused`, `UNSUPPORTED_BUNDLE`: a `ServiceRefused`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BUNDLE", "COMPUTE_ABI_MISMATCH", "UNSUPPORTED_BUNDLE" ], "x-calimero-details": { "BAD_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" }, "COMPUTE_ABI_MISMATCH": { "$ref": "#/components/schemas/ServiceRefused" }, "UNSUPPORTED_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/packages/{package}": { "delete": { "operationId": "ops_package_uninstall", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Uninstall what the operator installed", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uninstalled" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/packages/{package}/{version}": { "delete": { "operationId": "ops_package_version_uninstall", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Uninstall one operator-installed version", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uninstalled" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/placement": { "get": { "operationId": "ops_placement", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Where every app's replicas are", "description": "Ids and counts only, read after a read index (`fresh`: this node caught up with the system leader); `release` is a node's attested release; `clusterVersion` is the logged cluster version (`null` until the system leader logs one).\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fresh": { "type": "boolean" }, "apps": { "type": "array", "items": { "type": "object", "properties": { "app": { "type": "string" }, "group": { "type": "integer", "format": "int64", "minimum": 0 }, "replicas": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } } }, "required": [ "app", "group", "replicas" ] } }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "minimum": 0 }, "zone": { "type": "string" }, "role": { "$ref": "#/components/schemas/NodeRole" }, "release": { "type": [ "string", "null" ] }, "apps": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "id", "zone", "role", "release", "apps" ] } }, "clusterVersion": { "type": [ "string", "null" ] } }, "required": [ "fresh", "apps", "nodes", "clusterVersion" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/pools": { "get": { "operationId": "ops_pools_get", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Compute pools", "description": "The pools by name (absent: none set, one legacy pool), and each pool's capacity: how many runs its job nodes take at once.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "object", "additionalProperties": { "type": "object", "properties": { "runsPerNode": { "type": "integer", "format": "int64", "minimum": 0 }, "maxMemoryMib": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "runsPerNode", "maxMemoryMib" ] } }, "capacity": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 } } }, "required": [ "pools", "capacity" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } }, "post": { "operationId": "ops_pools_set", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Set the compute pools", "description": "Signed over `cluster / __set_pools / { pools }`; `POOL_IN_USE` when a pool to remove still has job nodes or runs.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pools": { "type": "object", "additionalProperties": { "type": "object", "properties": { "runsPerNode": { "type": "integer", "format": "int64", "minimum": 0 }, "maxMemoryMib": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "runsPerNode", "maxMemoryMib" ] } }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "pools" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`POOL_IN_USE`; `UPGRADE_PENDING`. `details` of `UPGRADE_PENDING`: a `UpgradePending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "POOL_IN_USE", "UPGRADE_PENDING" ], "x-calimero-details": { "UPGRADE_PENDING": { "$ref": "#/components/schemas/UpgradePending" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/prices": { "get": { "operationId": "ops_prices_get", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "The price table", "description": "In micro-units of the billing currency; `{}` until one is set.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "format": "int64", "minimum": 0 }, "fuelPerVcpuSecond": { "type": "integer", "format": "int64", "minimum": 0 }, "vcpuSecond": { "type": "integer", "format": "int64", "minimum": 0 }, "gibSecond": { "type": "integer", "format": "int64", "minimum": 0 }, "connectorGib": { "type": "integer", "format": "int64", "minimum": 0 }, "storageGibMonth": { "type": "integer", "format": "int64", "minimum": 0 }, "egressGib": { "type": "integer", "format": "int64", "minimum": 0 } } } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } }, "post": { "operationId": "ops_prices_set", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Set the price table", "description": "Signed over `cluster / __set_price_table / { table }`; `PRICE_VERSION` unless `version` is the current one plus one (1 for the first), `BAD_PRICES` for a zero `fuelPerVcpuSecond`.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table": { "type": "object", "properties": { "version": { "type": "integer", "format": "int64", "minimum": 0 }, "fuelPerVcpuSecond": { "type": "integer", "format": "int64", "minimum": 0 }, "vcpuSecond": { "type": "integer", "format": "int64", "minimum": 0 }, "gibSecond": { "type": "integer", "format": "int64", "minimum": 0 }, "connectorGib": { "type": "integer", "format": "int64", "minimum": 0 }, "storageGibMonth": { "type": "integer", "format": "int64", "minimum": 0 }, "egressGib": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "version", "fuelPerVcpuSecond", "vcpuSecond", "gibSecond", "connectorGib", "storageGibMonth", "egressGib" ] }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "table" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`BAD_PRICES`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_PRICES" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`PRICE_VERSION`; `UPGRADE_PENDING`. `details` of `UPGRADE_PENDING`: a `UpgradePending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "PRICE_VERSION", "UPGRADE_PENDING" ], "x-calimero-details": { "UPGRADE_PENDING": { "$ref": "#/components/schemas/UpgradePending" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/quotas": { "get": { "operationId": "ops_quotas_get", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "The quotas", "description": "The per-account quotas, and the per-payer overrides under `orgs`.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaSettings" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } }, "post": { "operationId": "ops_quotas_set", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Change quotas", "description": "Changes the limits the body names, the others keep their value; signed over `cluster / __set_quotas / { quotas }` with every limit after the change. Without `org`, the cluster's limits (`GET /ops/quotas` names them); `orgs`, which that answer carries, is ignored, so its answer may be sent back changed. With `org`: one payer's `maxConcurrentRuns`, `computeFuel` (decimal string) and `maxFileBytes` (`null` clears one, back to the cluster's), and no other limit. A property that is no limit (of the cluster's, or with `org` of a payer's) is refused `400 UNKNOWN_QUOTA`.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaChanges" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed; `UNKNOWN_QUOTA`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST", "UNKNOWN_QUOTA" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "409": { "description": "`UPGRADE_PENDING`. `details` of `UPGRADE_PENDING`: a `UpgradePending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UPGRADE_PENDING" ], "x-calimero-details": { "UPGRADE_PENDING": { "$ref": "#/components/schemas/UpgradePending" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/recover": { "post": { "operationId": "ops_recover", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Found the cluster again from its recovery disk", "description": "On the founder started with `--bootstrap --recover-from DIR`, its system state empty: the newest `system` file in `DIR/operator/` and the apps' `code` files, each with the data key the operator opened from it (hex). Checked as founding from backups is (governance, operator key, no node of the old cluster answering), then the system group is seeded; each app waits for `POST /ops/apps/{app}/restore { recovery }`.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "system": { "type": "object", "properties": { "file": { "type": "string" }, "key": { "type": "string" } }, "required": [ "file", "key" ] }, "code": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string" }, "key": { "type": "string" } }, "required": [ "file", "key" ] } } }, "required": [ "system" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "integer", "format": "int64", "minimum": 0 }, "accounts": { "type": "integer", "format": "int64", "minimum": 0 }, "index": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "apps", "accounts", "index" ] } } } }, "400": { "description": "`BAD_RECOVERY_FILE`; `BAD_RECOVERY_KEY`; `TOO_MANY_FILES`; `UNATTESTED_RECOVERY_FILE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_RECOVERY_FILE", "BAD_RECOVERY_KEY", "TOO_MANY_FILES", "UNATTESTED_RECOVERY_FILE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`NOT_RECOVERING`; `OLD_CLUSTER_ANSWERS`; `OTHER_DEPLOYMENT`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_RECOVERING", "OLD_CLUSTER_ANSWERS", "OTHER_DEPLOYMENT" ] } } } }, "/ops/recovery-files": { "get": { "operationId": "ops_recovery_files", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "The recovery files a node reads", "description": "In `--recover-from`, else `--recovery-dir`, of `holder` (`operator`, the default; `org:`; `account:`): each file's name, its header as signed (JSON text) and the node's Ed25519 signature over `calimero.recovery-backup.v1\\0` and those bytes (hex), for the holder's device to check before it opens a key with its own.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "parameters": [ { "name": "holder", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "holder": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "header": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "name", "header", "signature" ] } } }, "required": [ "holder", "files" ] } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`NO_BACKUP_DIR`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NO_BACKUP_DIR" ] } } } }, "/ops/releases": { "post": { "operationId": "ops_release", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Approve a mero-tee release for every app", "description": "Where the operator holds release approvals.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "approved": { "type": "boolean" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovedReleases" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/releases/{version}/deadline": { "post": { "operationId": "ops_release_deadline", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Set a release deadline", "description": "After `after` (RFC 3339), apps whose approver has not moved past the release may start no new work.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "after": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deadlines" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } }, "delete": { "operationId": "ops_release_deadline_lift", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Lift a release deadline", "description": "**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deadlines" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/served-origins": { "get": { "operationId": "ops_served", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Custom domains to serve", "description": "Every served origin a package's manager registered, by the package's label, never its name; `addedAt` is RFC 3339.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fresh": { "type": "boolean" }, "origins": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "host": { "type": "string" }, "label": { "type": "string" }, "addedAt": { "type": "string" } }, "required": [ "origin", "host", "label", "addedAt" ] } } }, "required": [ "fresh", "origins" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/sign-up": { "post": { "operationId": "ops_sign_up_set", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Set the sign-up policy", "description": "Refused once the cluster's owner runs sign-up.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/SignUp" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "policy" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpSet" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/sign-up/invites": { "post": { "operationId": "ops_sign_up_invite_create", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Issue a cluster sign-up invite", "description": "**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "uses": { "type": "integer", "format": "int64", "minimum": 0 }, "expiresAt": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "token", "expiresAt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpInvite" } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } }, "get": { "operationId": "ops_sign_up_invite_list", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Cluster sign-up invites", "description": "**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "signUp": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/SignUp" }, "orgInvites": { "type": "boolean" }, "signUpInvites": { "type": "boolean" }, "inviteRequired": { "type": "boolean" } }, "required": [ "policy", "orgInvites", "signUpInvites", "inviteRequired" ] }, "runBy": { "type": "string", "enum": [ "owner", "operator" ] }, "invites": { "type": "array", "items": { "$ref": "#/components/schemas/SignUpInvite" } } }, "required": [ "signUp", "runBy", "invites" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/ops/sign-up/invites/{key}": { "delete": { "operationId": "ops_sign_up_invite_revoke_delete", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Withdraw a cluster sign-up invite", "description": "**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteKey" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/sign-up/invites/{key}/revoke": { "post": { "operationId": "ops_sign_up_invite_revoke_post", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "Withdraw a cluster sign-up invite (POST)", "description": "For an HTTP client whose `DELETE` carries no body.\n\n**Who:** the ops token. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "x-calimero-operator": true, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteKey" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/ops/status": { "get": { "operationId": "ops_status", "tags": [ "Ops" ], "x-calimero-group": "ops", "summary": "The node and the cluster", "description": "Counts, Raft status and governance; never app state, names or credentials. `groups`: the app groups this node hosts; `apps` and `accounts` are counts; `rollback` is this node's rollback counter, `null` on a node without one.\n\n**Who:** the ops token.", "security": [ { "opsToken": [] } ], "x-calimero-who": "the ops token", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "system": { "$ref": "#/components/schemas/GroupStatus" }, "governance": { "$ref": "#/components/schemas/Governance" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "app": { "type": "string" }, "status": { "$ref": "#/components/schemas/GroupStatus" } }, "required": [ "app", "status" ] } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/NodeRecord" } }, "apps": { "type": "integer", "format": "int64", "minimum": 0 }, "accounts": { "type": "integer", "format": "int64", "minimum": 0 }, "rollback": { "anyOf": [ { "$ref": "#/components/schemas/RollbackStatus" }, { "type": "null" } ] } }, "required": [ "node", "system", "governance", "groups", "nodes", "apps", "accounts", "rollback" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] } } } }, "/orgs": { "post": { "operationId": "org_create", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Create an organization", "description": "`recoveryKey` is the public half of an organization recovery key. Every account also has a personal organization from sign-up (`personal` in `/auth/me`), which this does not make.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "recoveryKey": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgId": { "type": "string" } }, "required": [ "orgId" ] } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] } } } }, "/orgs/{org}": { "get": { "operationId": "org_get", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "One organization", "description": "As the directory records it, with only the teams the caller reaches or manages and the people they see; and its `mode` (from its app teams), the accounts that may approve its releases (`releaseApprovers`), the keys it publishes under (`publishes`), and `newWorkStopped`: the release whose passed deadline stops new work in it (`after`, RFC 3339), `null` when none does. Those four are absent from a node older than they are (1.0.0-rc.1 sends none of them).\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "org_delete", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Delete an organization", "description": "With its teams, invites and apps; the owner. `apps`: the apps deleted with it.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "string" } } }, "required": [ "apps" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/all-apps": { "post": { "operationId": "org_all_apps", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Give a member every app added later", "description": "Or stop it (`allApps: false`); apps already there are not touched. The owner or an admin; `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "allApps": { "type": "boolean" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "account", "allApps" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/app-teams": { "get": { "operationId": "app_team_list", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "The organization's app teams", "description": "A member: each app team's package, id, name, `join`, member count, default capabilities, and whether the caller is in it or manages it (a guest: only their own).\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "legacy", "standalone", "shared" ] }, "appTeams": { "type": "array", "items": { "type": "object", "properties": { "package": { "type": "string" }, "teamId": { "type": "string" }, "name": { "type": "string" }, "join": { "$ref": "#/components/schemas/TeamJoin" }, "memberCount": { "type": "integer", "format": "int64", "minimum": 0 }, "defaultCapabilities": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "member": { "type": "boolean" }, "manages": { "type": "boolean" } }, "required": [ "package", "teamId", "name", "join", "memberCount", "defaultCapabilities", "member", "manages" ] } } }, "required": [ "mode", "appTeams" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "post": { "operationId": "app_teams_scope", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Give apps app teams, or open or close one", "description": "The owner or an admin; `keep` names who stays when a team closes; `childTeams` says whether the app team's members make restricted teams below it (private channels), adding or removing `CREATE_CHILD_TEAM` (absent: as they are). Naming `join` or `childTeams` on any package leaves `shared` unset to mean no other team. `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "object", "properties": { "package": { "type": "string" }, "name": { "type": "string" }, "instances": { "type": "array", "items": { "type": "string" } }, "join": { "$ref": "#/components/schemas/TeamJoin" }, "keep": { "type": "array", "items": { "type": "string" } }, "childTeams": { "type": "boolean" } }, "required": [ "package" ] } }, "shared": { "type": "boolean" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "legacy", "standalone", "shared" ] }, "teams": { "type": "array", "items": { "type": "object", "properties": { "package": { "type": "string" }, "teamId": { "type": "string" }, "created": { "type": "boolean" }, "apps": { "type": "array", "items": { "type": "string" } }, "added": { "type": "integer", "format": "int64", "minimum": 0 }, "join": { "anyOf": [ { "$ref": "#/components/schemas/TeamJoin" }, { "type": "null" } ] }, "dropped": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "package", "teamId", "created", "apps", "added", "join", "dropped" ] } } }, "required": [ "mode", "teams" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `TOO_MANY_PACKAGES`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "TOO_MANY_PACKAGES", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/apps": { "get": { "operationId": "org_apps", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "The organization's apps", "description": "As `GET /auth/apps`, for the apps the caller reaches or manages; `404` to a non-member.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/AppScope" }, "governance": { "$ref": "#/components/schemas/Governance" }, "approvedReleases": { "type": [ "array", "null" ], "items": { "type": "string" } }, "clusterReleases": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterRelease" } }, "apps": { "type": "array", "items": { "$ref": "#/components/schemas/ReportApp" } }, "next": { "type": [ "string", "null" ] } }, "required": [ "scope", "governance", "approvedReleases", "clusterReleases", "apps", "next" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/backup-key": { "get": { "operationId": "org_backup_key", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "The organization's backup key", "description": "The X25519 public key its apps' recovery-disk backups are sealed to (`key`, `null` while none is set), and how many apps that covers. Any member; `404` outside the organization.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeyAnswer" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "post": { "operationId": "org_set_backup_key", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Set the organization's backup key", "description": "`publicKey`: 64 lowercase hex, an X25519 public key whose private half its holder keeps (never a node). Those who upgrade all the organization's apps (org-wide `MANAGE_APPLICATION`), where owners upgrade apps; replaces the key before. `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "publicKey" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupKeyAnswer" } } } }, "400": { "description": "`BAD_BACKUP_KEY`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BACKUP_KEY", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/capabilities": { "post": { "operationId": "org_capabilities", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Set capabilities", "description": "A member's (`account`), in a team (`team`), or a team's default; the capability bits. `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "team": { "type": "string" }, "capabilities": { "type": "integer", "format": "int64", "minimum": 0 }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "capabilities" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/invites": { "post": { "operationId": "invite_create", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Make an invite", "description": "A token for `role` and `teams`, `uses` times within `ttlSecs`; `allApps` (an admin's) also gives every app added later. `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/OrgRole" }, "teams": { "type": "array", "items": { "type": "string" } }, "ttlSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "uses": { "type": "integer", "format": "int64", "minimum": 0 }, "allApps": { "type": "boolean" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "get": { "operationId": "invite_list", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "The organization's invites", "description": "Their keys and terms, never a token: `expiresAt` Unix seconds; `createdBy` and `createdAt` are `null` on an invite from before they were kept.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "type": "object", "properties": { "inviteKey": { "type": "string" }, "role": { "$ref": "#/components/schemas/OrgRole" }, "teams": { "type": "array", "items": { "type": "string" } }, "usesLeft": { "type": "integer", "format": "int64", "minimum": 0 }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 }, "expired": { "type": "boolean" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "allApps": { "type": "boolean" } }, "required": [ "inviteKey", "role", "teams", "usesLeft", "expiresAt", "expired", "createdBy", "createdAt", "allApps" ] } } }, "required": [ "invites" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/invites/{key}": { "delete": { "operationId": "invite_revoke", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Revoke an invite", "description": "**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/members": { "get": { "operationId": "org_members", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Members' lockout risk", "description": "`detail=security` (the only listing: without it, or with another value, `400 BAD_REQUEST`), the owner or an admin: each member's passkeys (`1`, `2` or `\"3+\"`), recovery code, last active UTC day and sessions. `403` below admin, `404` outside the organization.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "security" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgId": { "type": "string" }, "members": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/OrgRole" }, "teams": { "type": "array", "items": { "type": "string" } }, "passkeys": { "anyOf": [ { "type": "integer", "format": "int64", "minimum": 0 }, { "type": "string", "enum": [ "3+" ] } ] }, "recoveryCode": { "type": "boolean" }, "lastActiveDay": { "type": [ "string", "null" ] }, "sessions": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "account", "name", "role", "teams", "passkeys", "recoveryCode", "lastActiveDay", "sessions" ] } } }, "required": [ "orgId", "members" ] } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "post": { "operationId": "org_set_member", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Set a member's role", "description": "`owner` moves ownership. `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "role": { "$ref": "#/components/schemas/OrgRole" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "account", "role" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/members/{account}": { "delete": { "operationId": "org_remove_member", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Remove a member, or leave", "description": "`412` first; the retry's JSON body is `{ confirm }`.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/members/{account}/metadata": { "post": { "operationId": "member_metadata", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Set a member's metadata", "description": "`metadata` is the caller's own JSON, free-form, kept as given.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/members/{account}/teams": { "post": { "operationId": "member_set_teams", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Set a member's rows in several teams", "description": "Each team judged as `POST /orgs/{org}/teams/{team}/members` would judge it, and none set unless every one may be (a row's absent `role` is `member`; absent `capabilities`, a new row takes the defaults and an existing row keeps its own). 1 to 64 distinct teams; one passkey, `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "string" }, "role": { "$ref": "#/components/schemas/TeamRole" }, "capabilities": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "team" ] } }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "teams" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`BAD_TEAMS`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_TEAMS", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "member_remove_teams", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Remove a member from several teams, or leave them", "description": "Each judged as `DELETE /orgs/{org}/teams/{team}/members/{account}` would judge it, and none taken unless every one may be. 1 to 64 distinct teams; one passkey, `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "string" } }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "teams" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`BAD_TEAMS`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_TEAMS", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/metadata": { "post": { "operationId": "org_metadata", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Set an organization's metadata", "description": "`metadata` is the caller's own JSON, free-form, kept as given.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/name": { "post": { "operationId": "org_rename", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Rename an organization", "description": "The owner or an admin, to a name that fits as a new organization's would; `412` first.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "orgId", "name" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/outbound": { "post": { "operationId": "org_outbound_approval", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Approve outbound prefixes for the organization's apps", "description": "The owner; `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "prefixes": { "$ref": "#/components/schemas/OutboundSelection" }, "replace": { "type": "boolean" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "package" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundApproved" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/packages/{package}/upgrade": { "post": { "operationId": "publisher_upgrade", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Upgrade every instance of a publisher's package", "description": "An upgrade run over every app on the cluster that runs the package, by its publisher's `MANAGE_APPLICATION` holders.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "migrate": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeRun" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/publishers": { "post": { "operationId": "org_publisher", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Bind a package signing key", "description": "The key's signature over the binding proves the organization holds it; then its `MANAGE_APPLICATION` holders upgrade the apps of packages that name `publisher`. Answers the key's binding generation now.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signerId": { "type": "string" }, "publicKey": { "type": "string" }, "signature": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "signerId", "publicKey", "signature" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "generation": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "generation" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/recovery": { "post": { "operationId": "recovery_set", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Set the organization's recovery key", "description": "Set or rotate it (`publicKey`: base64url Ed25519 public key), or remove it (`publicKey: null`; an absent `publicKey` removes it too); the owner; cancels a recovery under way. `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publicKey": { "type": [ "string", "null" ] }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`BAD_RECOVERY_KEY`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_RECOVERY_KEY", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/recovery/cancel": { "post": { "operationId": "recovery_cancel", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Cancel an organization recovery", "description": "The owner; `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/recovery/finish": { "post": { "operationId": "recovery_finish", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Finish an organization recovery", "description": "The account that started it, once `readyAt` passed; `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "org": { "type": "string" }, "previousOwners": { "type": "array", "items": { "type": "string" } } }, "required": [ "org", "previousOwners" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "409": { "description": "`RECOVERY_NOT_READY`. `details` of `RECOVERY_NOT_READY`: a `RecoveryNotReady`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RECOVERY_NOT_READY" ], "x-calimero-details": { "RECOVERY_NOT_READY": { "$ref": "#/components/schemas/RecoveryNotReady" } } }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/recovery/start": { "post": { "operationId": "recovery_start", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Start an organization recovery", "description": "The recovery seed's signature handing the organization to the caller.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "nonce", "signature" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "startedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "readyAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "startedAt", "readyAt" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only); `WRONG_RECOVERY_KEY`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN", "WRONG_RECOVERY_KEY" ] }, "409": { "description": "`RECOVERY_PENDING`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "RECOVERY_PENDING" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/releases": { "post": { "operationId": "org_release_approval", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Approve a mero-tee release for the organization's apps", "description": "The owner; `412` first.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "approved": { "type": "boolean" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovedReleases" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/teams": { "post": { "operationId": "team_create", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Create a team", "description": "An admin, a lead of `parent`, a member with `CREATE_TEAM` at the top, or a member who holds `CREATE_CHILD_TEAM` under `parent` (a restricted team only). A package-bound session: only its own package's teams (its app team and the teams below it): `parent` one of them.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "parent": { "type": "string" }, "join": { "$ref": "#/components/schemas/TeamJoin" } }, "required": [ "name", "join" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "type": "string" } }, "required": [ "teamId" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/teams/{team}": { "get": { "operationId": "team_get", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "One team", "description": "**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "team", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamView" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "post": { "operationId": "team_update", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Update a team", "description": "Rename, open or restrict, move under another parent, or set its metadata (the caller's own JSON, free-form, kept as given). `parent` absent leaves the team where it is; `parent: null` (an explicit null) moves it to the top; a team id moves it under that team. A package-bound session: only its own package's teams (its app team and the teams below it): a team below its app team, moved only within.\n\n**Who:** a passkey session (an API key is refused).", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "team", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "join": { "$ref": "#/components/schemas/TeamJoin" }, "parent": { "type": [ "string", "null" ] }, "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "team_delete", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Delete a team", "description": "With the teams and apps below it. A package-bound session: only its own package's teams (its app team and the teams below it): a team below its app team whose apps are all its package's.\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "team", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "type": "string" } }, "apps": { "type": "array", "items": { "type": "string" } } }, "required": [ "teams", "apps" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/teams/{team}/members": { "post": { "operationId": "team_set_member", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Add or change a team member", "description": "A package-bound session: only its own package's teams (its app team and the teams below it).\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "team", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "lead": { "type": "boolean" }, "role": { "$ref": "#/components/schemas/TeamRole" }, "capabilities": { "type": "integer", "format": "int64", "minimum": 0 }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "account" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/teams/{team}/members/{account}": { "delete": { "operationId": "team_remove_member", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Remove a team member, or leave", "description": "A package-bound session: only its own package's teams (its app team and the teams below it).\n\n**Who:** a passkey session (an API key is refused). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "a passkey session (an API key is refused)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "team", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/upgrade": { "post": { "operationId": "org_upgrade", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Start an upgrade run", "description": "Upgrade every app of the organization (or of `team`, with `cascade` its subtree) that runs `package` to `version`, with one passkey assertion over the whole run; whoever holds `MANAGE_APPLICATION` there. Each app is upgraded as `POST /apps/{app}/upgrade` would; `GET /orgs/{org}/upgrades/{run}` follows it.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "team": { "type": "string" }, "cascade": { "type": "boolean" }, "migrate": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "package", "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeRun" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/upgrades/{run}": { "get": { "operationId": "org_upgrade_status", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "An upgrade run's progress", "description": "A member of the organization.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeRun" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/orgs/{org}/upgrades/{run}/retry": { "post": { "operationId": "org_upgrade_retry", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "Retry an upgrade run's failed apps", "description": "As a new run under the same terms: a passkey step-up for a member's run, the operator's signature for an operator's run (with the ops token).\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "x-calimero-operator": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "$ref": "#/components/schemas/Confirm" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } } } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeRun" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE", "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/orgs/{org}/usage": { "get": { "operationId": "org_usage", "tags": [ "Organizations" ], "x-calimero-group": "orgs", "summary": "An organization's usage", "description": "An admin: how many apps the organization develops, what their runs used today (decimal strings) and the cluster's quotas; a member gets `403`.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "org", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "integer", "format": "int64", "minimum": 0 }, "developerFuelToday": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "developerWritesToday": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "quotas": { "$ref": "#/components/schemas/Quotas" } }, "required": [ "apps", "developerFuelToday", "developerWritesToday", "quotas" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/package-origins/{package}": { "get": { "operationId": "origins_list", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "A package's frontend origins", "description": "The custom origins (and rp-ids) the package's manager registered for its frontend.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "origins": { "type": "array", "items": { "$ref": "#/components/schemas/PackageOrigin" } } }, "required": [ "package", "origins" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "post": { "operationId": "origins_add", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Register a frontend origin", "description": "By whoever manages the package, with a passkey step-up over the change. Answers the origin as registered (the one already there, when the same origin is registered again).\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin": { "type": "string" }, "rpId": { "type": "string" }, "served": { "type": "boolean" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "origin" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageOrigin" } } } }, "400": { "description": "`BAD_RP_ID`; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_RP_ID", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] }, "429": { "description": "`QUOTA_EXCEEDED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "QUOTA_EXCEEDED" ] } } }, "delete": { "operationId": "origins_remove", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Remove a frontend origin", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin": { "type": "string" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "origin" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "origin": { "type": "string" }, "removed": { "type": "boolean" } }, "required": [ "package", "origin", "removed" ] } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/packages": { "post": { "operationId": "package_upload", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Upload a signed release", "description": "A signed `.mpk`, checked as an install from the registry is (signature, artifact digests, `minRuntimeVersion`, the package's pinned signer, every service compiles). Only with `--dev`; otherwise `403 UPLOADS_DISABLED`.\n\n**Who:** an installer (an account holder, or an unscoped API key that is not read-only).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "an installer (an account holder, or an unscoped API key that is not read-only)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream" } } }, "description": "the `.mpk`" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "signerId": { "type": "string" }, "services": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "package", "version", "signerId", "services" ] } } } }, "400": { "description": "`BAD_BUNDLE`; `BAD_PACKAGE`; `COMPUTE_ABI_MISMATCH`; `UNSUPPORTED_BUNDLE`. `details` of `BAD_BUNDLE`: a `ServiceRefused`, `COMPUTE_ABI_MISMATCH`: a `ServiceRefused`, `UNSUPPORTED_BUNDLE`: a `ServiceRefused`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BUNDLE", "BAD_PACKAGE", "COMPUTE_ABI_MISMATCH", "UNSUPPORTED_BUNDLE" ], "x-calimero-details": { "BAD_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" }, "COMPUTE_ABI_MISMATCH": { "$ref": "#/components/schemas/ServiceRefused" }, "UNSUPPORTED_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`DEPLOY_NOT_GRANTED`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only); `UPLOADS_DISABLED`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "DEPLOY_NOT_GRANTED", "FORBIDDEN", "UPLOADS_DISABLED" ] }, "413": { "description": "`TOO_LARGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "TOO_LARGE" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "get": { "operationId": "package_list", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Installed packages", "description": "Only the releases the caller may see.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } } }, "required": [ "packages" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/packages/install": { "post": { "operationId": "package_install", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Install a release from the registry", "description": "**Who:** an installer (an account holder, or an unscoped API key that is not read-only).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "an installer (an account holder, or an unscoped API key that is not read-only)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" } }, "required": [ "package", "version" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "signerId": { "type": "string" }, "services": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "package", "version", "signerId", "services" ] } } } }, "400": { "description": "`BAD_BUNDLE`; `BAD_PACKAGE`; `COMPUTE_ABI_MISMATCH`; `NO_REGISTRY`; `UNSUPPORTED_BUNDLE`. `details` of `BAD_BUNDLE`: a `ServiceRefused`, `COMPUTE_ABI_MISMATCH`: a `ServiceRefused`, `UNSUPPORTED_BUNDLE`: a `ServiceRefused`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_BUNDLE", "BAD_PACKAGE", "COMPUTE_ABI_MISMATCH", "NO_REGISTRY", "UNSUPPORTED_BUNDLE" ], "x-calimero-details": { "BAD_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" }, "COMPUTE_ABI_MISMATCH": { "$ref": "#/components/schemas/ServiceRefused" }, "UNSUPPORTED_BUNDLE": { "$ref": "#/components/schemas/ServiceRefused" } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`DEPLOY_NOT_GRANTED`; `FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "DEPLOY_NOT_GRANTED", "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/packages/{package}": { "get": { "operationId": "package_get", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "One package", "description": "The versions the caller may see; `404` when none.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Package" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "delete": { "operationId": "package_uninstall", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Uninstall a package", "description": "Every version; refused while an app runs one.\n\n**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uninstalled" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/packages/{package}/{version}": { "delete": { "operationId": "package_version_uninstall", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "Uninstall one version", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Uninstalled" } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/packages/{package}/{version}/pipelines": { "get": { "operationId": "package_pipelines", "tags": [ "Packages" ], "x-calimero-group": "packages", "summary": "A release's pipelines", "description": "The pipelines the release registers, by name: `hash`, `worstCaseFuel` (a decimal string), the `modules` they pin and the canonical `pipeline`. `404` for a release the caller may not see.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "package", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "hash": { "type": "string" }, "worstCaseFuel": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "modules": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "pipeline": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "hash", "worstCaseFuel", "modules", "pipeline" ] } } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/pipelines/validate": { "post": { "operationId": "pipelines_validate", "tags": [ "Apps" ], "x-calimero-group": "apps", "summary": "Validate a pipeline", "description": "Every problem of `source`; with `package` and `version` (both, a release the caller sees) also against that release's methods, modules and the cluster's pools. Writes nothing.\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" } }, "required": [ "source" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "code", "message" ] } }, "pipeline": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "worstCaseFuel": { "type": "string" }, "worstCaseCost": { "type": "string" } }, "required": [ "ok", "errors" ] } } } }, "400": { "description": "`BAD_RELEASE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_RELEASE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "404": { "description": "`NOT_FOUND`: no such object, or one the caller may not see", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "NOT_FOUND" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/publishers/{signer}": { "get": { "operationId": "publisher_binding", "tags": [ "Public" ], "x-calimero-group": "public", "summary": "Whether a signing key is bound", "description": "Whether a package signing key (`did:key`) is bound to an organization on this cluster (`bound`, never which), and its binding generation (`0`: never bound).\n\n**Who:** signed in (a session or an API key).", "security": [ { "session": [] }, { "apiKey": [] } ], "x-calimero-who": "signed in (a session or an API key)", "x-calimero-sealed": true, "parameters": [ { "name": "signer", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "signerId": { "type": "string" }, "cluster": { "type": "string" }, "generation": { "type": "integer", "format": "int64", "minimum": 0 }, "bound": { "type": "boolean" } }, "required": [ "signerId", "cluster", "generation", "bound" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/recover/holder": { "post": { "operationId": "restore_recover_holder", "tags": [ "Public" ], "x-calimero-group": "public", "summary": "Bring an organization's or account's apps back from its recovery files", "description": "Sent by the holder's own device, over the sealed channel: its newest `holder` file (`slice`), each app's file and the code files, in the receiving node's `--recovery-dir` (or `--recover-from`) under `org-/` or `account-/`, each with the data key the holder opened from it with its backup key (hex). The cluster admits it with the operator's signature over `cluster / __recover_holder / { holder, slice, apps: [{ app, file, sha256 }] }` (`428` first, naming it). Where owners upgrade apps, and only for an organization, account, apps and passkeys the cluster does not hold; the receiving node seeds each app, which answers `409 APP_RESTORING` until its replicas hold it. People sign in again with the passkeys they had.\n\n**Who:** anyone. **Operator signature:** answers `428 OPERATOR_SIGNATURE_REQUIRED` first; send it again with `operatorProof`, the operator key's signature over `details.message` and its `nonce`.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "x-calimero-operator": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "holder": { "type": "string" }, "slice": { "type": "object", "properties": { "file": { "type": "string" }, "key": { "type": "string" } }, "required": [ "file", "key" ] }, "apps": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string" }, "key": { "type": "string" } }, "required": [ "file", "key" ] } }, "code": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string" }, "key": { "type": "string" } }, "required": [ "file", "key" ] } }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "required": [ "holder", "slice" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "apps" ] } } } }, "400": { "description": "`BAD_RECOVERY_FILE`; `BAD_RECOVERY_KEY`; `BAD_REQUEST`: the request is malformed; `NOT_A_REPLICA_NODE`; `TOO_MANY_FILES`; `UNATTESTED_RECOVERY_FILE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_RECOVERY_FILE", "BAD_RECOVERY_KEY", "BAD_REQUEST", "NOT_A_REPLICA_NODE", "TOO_MANY_FILES", "UNATTESTED_RECOVERY_FILE" ] }, "403": { "description": "`BAD_OPERATOR_SIGNATURE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_OPERATOR_SIGNATURE" ] }, "409": { "description": "`FEATURE_NOT_ACTIVE`; `NO_BACKUP_DIR`; `RECOVERY_SEGMENTS_MISSING`. `details` of `FEATURE_NOT_ACTIVE`: a `FeatureNotActive`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FEATURE_NOT_ACTIVE", "NO_BACKUP_DIR", "RECOVERY_SEGMENTS_MISSING" ], "x-calimero-details": { "FEATURE_NOT_ACTIVE": { "$ref": "#/components/schemas/FeatureNotActive" } } }, "428": { "description": "`OPERATOR_SIGNATURE_REQUIRED`: the operator key must sign the decision; `details` names the statement. `details` of `OPERATOR_SIGNATURE_REQUIRED`: a `OperatorSignatureRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "OPERATOR_SIGNATURE_REQUIRED" ], "x-calimero-details": { "OPERATOR_SIGNATURE_REQUIRED": { "$ref": "#/components/schemas/OperatorSignatureRequired" } } } } } }, "/releases": { "get": { "operationId": "releases_public", "tags": [ "Public" ], "x-calimero-group": "public", "summary": "The cluster's releases", "description": "The cluster's governance and the deadlines set on mero-tee releases, oldest release first: after `after` (RFC 3339; `afterSecs` Unix seconds) a scope that has not approved that release (or a newer one) starts no new work.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "governance": { "$ref": "#/components/schemas/Governance" }, "deadlines": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "after": { "type": "string" }, "afterSecs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "version", "after", "afterSecs" ] } } }, "required": [ "governance", "deadlines" ] } } } } } } }, "/sign-up": { "get": { "operationId": "sign_up_public", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "The sign-up policy", "description": "Who may create an account here, the cluster's name and the tag a sign-in uses to pick the person's passkey for it.\n\n**Who:** anyone.", "security": [], "x-calimero-who": "anyone", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/SignUp" }, "orgInvites": { "type": "boolean" }, "signUpInvites": { "type": "boolean" }, "inviteRequired": { "type": "boolean" }, "cluster": { "type": "string" }, "passkeyTag": { "type": "string" } }, "required": [ "policy", "orgInvites", "signUpInvites", "inviteRequired", "cluster", "passkeyTag" ] } } } } } }, "post": { "operationId": "sign_up_set", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Set the sign-up policy", "description": "The cluster's owner, once named, with a passkey (`412` first).\n\n**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/SignUp" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "required": [ "policy" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpSet" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/sign-up/invites": { "post": { "operationId": "sign_up_invite_create", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Issue a cluster sign-up invite", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uses": { "type": "integer", "format": "int64", "minimum": 0 }, "ttlSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "confirm": { "$ref": "#/components/schemas/Confirm" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "inviteKey": { "type": "string" }, "uses": { "type": "integer", "format": "int64", "minimum": 0 }, "expiresAt": { "type": "string" }, "expiresAtSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "token", "inviteKey", "uses", "expiresAt", "expiresAtSecs", "createdBy", "createdAt" ] } } } }, "400": { "description": "`BAD_REQUEST`: the request is malformed; `EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`; `WRONG_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "BAD_REQUEST", "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE", "WRONG_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } }, "get": { "operationId": "sign_up_invite_list", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Cluster sign-up invites", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend).", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "signUp": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/SignUp" }, "orgInvites": { "type": "boolean" }, "signUpInvites": { "type": "boolean" }, "inviteRequired": { "type": "boolean" } }, "required": [ "policy", "orgInvites", "signUpInvites", "inviteRequired" ] }, "runBy": { "type": "string", "enum": [ "owner", "operator" ] }, "invites": { "type": "array", "items": { "$ref": "#/components/schemas/SignUpInvite" } } }, "required": [ "signUp", "runBy", "invites" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } }, "/sign-up/invites/{key}": { "delete": { "operationId": "sign_up_invite_revoke", "tags": [ "Sign-up and deployments" ], "x-calimero-group": "deployments", "summary": "Withdraw a cluster sign-up invite", "description": "**Who:** an account holder (a passkey session not bound to an app's frontend). **Step-up:** answers `412 CONFIRM_REQUIRED` first; send the same request again with `confirm`, a passkey assertion over `details.challenge`.", "security": [ { "session": [] } ], "x-calimero-who": "an account holder (a passkey session not bound to an app's frontend)", "x-calimero-sealed": true, "x-calimero-step-up": true, "x-calimero-user-verification": "required", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOnly" } } }, "description": "May be absent." }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteKey" } } } }, "400": { "description": "`EXPIRED_CHALLENGE`; `UNKNOWN_CHALLENGE`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "EXPIRED_CHALLENGE", "UNKNOWN_CHALLENGE" ] }, "401": { "description": "`UNAUTHENTICATED`: no, unknown, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "UNAUTHENTICATED" ] }, "403": { "description": "`FORBIDDEN`: the credential may not do this (scope, role, governance, read-only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "FORBIDDEN" ] }, "412": { "description": "`CONFIRM_REQUIRED`: a passkey assertion is needed; `details` carries the challenge. `details` of `CONFIRM_REQUIRED`: a `ConfirmRequired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "CONFIRM_REQUIRED" ], "x-calimero-details": { "CONFIRM_REQUIRED": { "$ref": "#/components/schemas/ConfirmRequired" } } }, "421": { "description": "`WRONG_NODE`: this node runs a release the account's owners have not approved, so it neither issues nor takes the account's sessions; send it to another node of the cluster (no `details`; nothing was spent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-calimero-codes": [ "WRONG_NODE" ] } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "status": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "type": "string" }, "message": { "type": "string" }, "details": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "status", "error", "message" ], "description": "An error answer: `error` is the code. `details`, absent for most codes, has the schema `x-calimero-details` names for the code on the operation's response (every code's: `x-calimero-error-details` at the document's root); a code it names no schema for carries none, or a value clients need not read." }, "Confirm": { "type": "object", "properties": { "challengeId": { "type": "string" }, "assertion": { "$ref": "#/components/schemas/Assertion" } }, "required": [ "challengeId", "assertion" ], "description": "A passkey assertion over the challenge a `412 CONFIRM_REQUIRED` named: the same request sent again with it approves exactly that request." }, "ConfirmRequired": { "type": "object", "properties": { "challengeId": { "type": "string" }, "challenge": { "type": "string", "contentEncoding": "base64url", "description": "base64url (RFC 4648 section 5) without padding" }, "rpId": { "type": "string" }, "allowCredentials": { "type": "array", "items": { "type": "string" } }, "apps": { "type": "array", "items": { "type": "string" } } }, "required": [ "challengeId", "challenge", "rpId", "allowCredentials" ], "description": "`details` of a `412 CONFIRM_REQUIRED`: the WebAuthn challenge to sign under `rpId` with one of the passkeys `allowCredentials` names (credential ids; empty: any of the account's), and the `challengeId` the retry's `confirm` names. `apps`: deleting a team that holds apps, the apps that go with it." }, "OperatorProof": { "type": "object", "properties": { "nonce": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "nonce", "signature" ], "description": "The operator key's Ed25519 signature (hex) over the statement a `428 OPERATOR_SIGNATURE_REQUIRED` named, with that statement's nonce." }, "OperatorSignatureRequired": { "type": "object", "properties": { "subject": { "type": "string" }, "method": { "type": "string" }, "args": { "type": "string" }, "nonce": { "type": "string" }, "cluster": { "type": "string" }, "message": { "type": "string" } }, "required": [ "subject", "method", "args", "nonce", "cluster", "message" ], "description": "`details` of a `428 OPERATOR_SIGNATURE_REQUIRED`: the statement to sign (`args` is the JSON text of its arguments, as signed) and the exact bytes to sign (`message`, standard base64)." }, "Assertion": { "type": "object", "properties": { "credentialId": { "type": "string" }, "authenticatorData": { "type": "string" }, "clientDataJson": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "credentialId", "authenticatorData", "clientDataJson", "signature" ], "description": "The browser's answer to `navigator.credentials.get`, each field base64url." }, "Registration": { "type": "object", "properties": { "attestationObject": { "type": "string" }, "clientDataJson": { "type": "string" } }, "required": [ "attestationObject", "clientDataJson" ], "description": "The browser's answer to `navigator.credentials.create`, each field base64url." }, "Session": { "type": "object", "properties": { "accountId": { "type": "string" }, "sessionToken": { "type": "string" }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 }, "refreshToken": { "type": "string" } }, "required": [ "accountId", "sessionToken", "expiresAt", "refreshToken" ], "description": "A session: its token (15 minutes, by the issuing node) and the refresh token for `/auth/refresh`." }, "BackupKeyAnswer": { "type": "object", "properties": { "holder": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "operator", "org", "account" ] }, "id": { "type": "string" } }, "required": [ "kind" ] }, "key": { "type": [ "object", "null" ], "properties": { "publicKey": { "type": "string" }, "setAt": { "type": "integer", "format": "int64", "minimum": 0 }, "setBy": { "type": "string" } }, "required": [ "publicKey", "setAt", "setBy" ] }, "apps": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "holder", "key", "apps" ], "description": "A holder's backup key: who holds it (`{ kind: \"operator\" }`, `{ kind: \"org\", id }` or `{ kind: \"account\", id }`), the X25519 public key the recovery disk seals their apps' backups to (`null` while none is set), and how many apps that covers." }, "Applied": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "status": { "type": "string", "enum": [ "ok", "appError", "trap" ] }, "error": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "index", "status", "error" ], "description": "An entry an app's log applied: its index, how it ended and the app's error (`null` when it ended `ok`; the app's own error value otherwise, free-form). `details` of a `422 UPGRADE_FAILED`." }, "NotLeader": { "type": "object", "properties": { "leaderUrl": { "type": "string" }, "leader": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "leaderUrl" ], "description": "`details` of a `421 NOT_LEADER`: the leader's URL to send the same request to, and its node id where known." }, "FeatureNotActive": { "type": "object", "properties": { "feature": { "type": "string" }, "needs": { "type": "string" }, "active": { "type": [ "string", "null" ] } }, "required": [ "feature", "needs", "active" ], "description": "`details` of a `409 FEATURE_NOT_ACTIVE`: the feature the request needs, the cluster version it ships in (`needs`) and the version active now (`null`: none logged, and the nodes could not say)." }, "RuntimeTooOld": { "type": "object", "properties": { "minRuntimeVersion": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "before": { "type": "string" } }, "required": [ "before" ] } ] } }, "required": [ "node", "runtime" ] } } }, "required": [ "minRuntimeVersion", "nodes" ], "description": "`details` of a `409 RUNTIME_TOO_OLD`: the runtime the release needs and the replicas known to fall short of it, each with what it runs (a version, or `{ before }`: a release older than that one)." }, "ReleaseDeadline": { "type": "object", "properties": { "release": { "type": "string" }, "after": { "type": "string" }, "afterSecs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "release", "after", "afterSecs" ], "description": "`details` of a `409 RELEASE_DEADLINE`: the mero-tee release whose deadline passed, and the deadline (`after` RFC 3339, `afterSecs` Unix seconds). Approving that release (or a newer one) lifts it." }, "UpgradePending": { "type": "object", "properties": { "release": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "release": { "type": [ "string", "null" ] } }, "required": [ "node", "release" ] } } }, "required": [ "release", "nodes" ], "description": "`details` of a `409 UPGRADE_PENDING`: the release every node must run first, and the nodes that run an older one (`release` `null`: one this node could not attest)." }, "AppError": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "code": { "type": "string" }, "fields": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "code", "fields" ], "description": "`details` of a `422 APP_ERROR`: the app's error code, its fields (the app's own value, free-form: the object its ABI declares for the error, or the app's message as a string when that is not JSON), and the log index of the call (absent when the node refused it before it ran: `UnknownMethod`, `WrongKind`, `Forbidden`, `ConfirmNotAView`, `NotAView`, `ConfirmRequired`)." }, "Trap": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64", "minimum": 0 }, "kind": { "type": "string", "enum": [ "OutOfFuel", "Timeout", "Cancelled", "Unavailable", "OutOfMemory", "StackOverflow", "Fault", "HostDenied" ] }, "detail": { "type": "string" } }, "required": [ "index", "kind", "detail" ], "description": "`details` of a `422 TRAP`: the log index of the run, how it trapped, and the engine's account of it." }, "InitFailed": { "type": "object", "properties": { "appId": { "type": "string" }, "error": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." } }, "required": [ "appId", "error" ], "description": "`details` of a `422 INIT_FAILED`: the app made, and the error its `init` ended with (the app log's, free-form)." }, "RecoveryNotReady": { "type": "object", "properties": { "readyAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "readyAt" ], "description": "`details` of a `409 RECOVERY_NOT_READY`: when the recovery may finish (Unix seconds)." }, "UploadPosition": { "type": "object", "properties": { "next": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "next" ], "description": "`details` of a `409 PART_CONFLICT`, `409 PART_OUT_OF_ORDER` or `409 UPLOAD_INCOMPLETE`: the part the upload expects next." }, "RetryAfter": { "type": "object", "properties": { "retryAfter": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "retryAfter" ], "description": "`details` of a `503 TIMEOUT` or `503 FILES_UNAVAILABLE`: the seconds to wait before sending the same request (with the same idempotency key) again." }, "ServiceRefused": { "type": "object", "properties": { "service": { "type": "string" }, "compute": { "type": "boolean" } }, "required": [ "service" ], "description": "`details` of a `400 UNSUPPORTED_BUNDLE`, `400 BAD_BUNDLE` or `400 COMPUTE_ABI_MISMATCH` refusing one service of a release: the service, and `compute: true` when it was that service's compute component. Absent when the refusal is of a raw bundle." }, "SealedRefusal": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "description": "The sealed channel's own refusal, outside the envelope and in the clear: not an `Error`. `busy` (`503`, with `Retry-After: 1`): too many sealed requests or sessions at once, send it again; the other codes (`400`, `malformed` and the like) say the envelope could not be opened." }, "Receipt": { "type": "object", "properties": { "app": { "type": "string" }, "index": { "type": "integer", "format": "int64", "minimum": 0 }, "resultHash": { "type": "string" }, "node": { "type": "integer", "format": "int64", "minimum": 0 }, "key": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "app", "index", "resultHash", "node", "key", "signature" ], "description": "The answering node's signature (receipt key, hex) over `(app, index, SHA-256(JCS(result)), node)`." }, "Access": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "owner" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "org" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "public" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "accounts" ] }, "accounts": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "accounts" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "team" ] }, "team": { "type": "string" } }, "required": [ "kind", "team" ] } ], "discriminator": { "propertyName": "kind" }, "description": "Who may reach an app at all." }, "OrgRole": { "type": "string", "enum": [ "guest", "member", "admin", "owner" ], "description": "A member's role in an organization." }, "TeamRole": { "type": "string", "enum": [ "lead", "member", "readOnly" ], "description": "A member's standing in one team." }, "TeamJoin": { "type": "string", "enum": [ "everyone", "invite" ], "description": "Open (`everyone` who reaches the parent) or restricted (`invite`) membership." }, "OutboundSelection": { "anyOf": [ { "type": "string", "enum": [ "manifest" ] }, { "type": "array", "items": { "type": "string" } } ], "description": "`manifest` (every prefix the release declares) or these prefixes." }, "Deployer": { "oneOf": [ { "type": "object", "properties": { "account": { "type": "string" } }, "required": [ "account" ] }, { "type": "object", "properties": { "org": { "type": "string" } }, "required": [ "org" ] } ], "description": "An account or an organization." }, "SignUp": { "type": "string", "enum": [ "open", "invite", "closed" ], "description": "The cluster's sign-up policy." }, "Page": { "type": "object", "properties": { "next": { "type": [ "string", "null" ] } }, "required": [ "next" ], "description": "A page of a list: `next` is the `after` of the next page, `null` on the last." }, "Release": { "type": "object", "properties": { "version": { "type": "string" }, "profile": { "type": "string" } }, "required": [ "version", "profile" ], "description": "A mero-tee release." }, "AttestationDoc": { "type": "object", "properties": { "quote": { "type": "string" }, "transportKey": { "type": "string" }, "appHash": { "type": "string" }, "nonce": { "type": "string" }, "release": { "$ref": "#/components/schemas/Release" }, "cluster": { "type": "string" }, "node": { "type": "integer", "format": "int64", "minimum": 0 }, "mock": { "type": "boolean" }, "receiptKey": { "type": "string" }, "governance": { "$ref": "#/components/schemas/Governance" }, "kms": { "$ref": "#/components/schemas/KmsKeys" }, "jobKey": { "type": "string" }, "clusterIdentity": { "type": "string" } }, "required": [ "quote", "transportKey", "appHash", "nonce", "release", "cluster", "node", "mock" ], "description": "A node's attestation: the TDX quote (base64), the key it binds (hex) and what it was asked for. `receiptKey` and `governance` with `purpose=receipts`, `kms` with `purpose=kms` on a node with a KMS record, `clusterIdentity` with `purpose=orchestrator`; `jobKey` only from a job node, never from this API." }, "KmsKeys": { "type": "object", "properties": { "storage": { "$ref": "#/components/schemas/KmsEvidence" }, "disk": { "$ref": "#/components/schemas/KmsEvidence" } }, "description": "What a node verified of the mero-kms replicas it took its keys from: the storage key `merod` fetched, and the data disk's key the boot script fetched; each absent without a record." }, "KmsEvidence": { "type": "object", "properties": { "kmsHost": { "type": "string" }, "release": { "type": "string" }, "profile": { "type": "string" }, "mrtd": { "type": "string" }, "rtmr0": { "type": "string" }, "rtmr1": { "type": "string" }, "rtmr2": { "type": "string" }, "rtmr3": { "type": "string" }, "tcbStatus": { "type": "string" }, "quoteSha256": { "type": "string" }, "verifiedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "mock": { "type": "boolean" } }, "required": [ "kmsHost", "release", "mrtd", "rtmr0", "rtmr1", "rtmr2", "rtmr3", "quoteSha256", "verifiedAt" ], "description": "The KMS quote a node accepted a key under: the KMS host, the mero-kms release (and image profile) whose signed policy it matched, the quote's registers (hex), its TCB status, SHA-256 and when it was verified (Unix seconds); `mock` (absent: false) in development builds only." }, "GroupStatus": { "type": "object", "properties": { "group": { "type": "integer", "format": "int64", "minimum": 0 }, "leader": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "is_leader": { "type": "boolean" }, "term": { "type": "integer", "format": "int64", "minimum": 0 }, "last_log": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "applied": { "type": "integer", "format": "int64", "minimum": 0 }, "voters": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "learners": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } } }, "required": [ "group", "leader", "is_leader", "term", "last_log", "applied", "voters", "learners" ], "description": "A Raft group's status as one node sees it: the leader (`null`: none known), whether this node is it, the term, the last log index (`null`: an empty log), the applied index, and the voters and learners." }, "RollbackStatus": { "type": "object", "properties": { "epoch": { "type": "integer", "format": "int64", "minimum": 0 }, "generation": { "type": "integer", "format": "int64", "minimum": 0 }, "mark": { "type": "integer", "format": "int64", "minimum": 0 }, "forced": { "type": "boolean" }, "sinceCheckpointSecs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "epoch", "generation", "mark", "forced", "sinceCheckpointSecs" ], "description": "A node's rollback counter: the cluster's epoch (rollbacks forced so far), its generation and mark, whether this start was forced (`--accept-rollback`), and the seconds since mero-kms last acknowledged a checkpoint." }, "NodeRole": { "type": "string", "enum": [ "replica", "job" ], "description": "What a node does: hold app replicas, or run compute jobs." }, "NodeRecord": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "minimum": 0 }, "addr": { "type": "string" }, "zone": { "type": "string" }, "role": { "$ref": "#/components/schemas/NodeRole" }, "pool": { "type": "string" } }, "required": [ "id", "addr", "zone", "role" ], "description": "A registered node: its id, address, zone, role and (a job node's) compute pool, absent for none." }, "Quotas": { "type": "object", "properties": { "maxAppsPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxBundleBytesPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxApiKeysPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxOrgsPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxAccounts": { "type": "integer", "format": "int64", "minimum": 0 }, "maxFileBytesPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "maxConcurrentRunsPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "computeFuelPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "maxFuelPerDeveloperPerDay": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" } }, "required": [ "maxAppsPerAccount", "maxBundleBytesPerAccount", "maxApiKeysPerAccount", "maxOrgsPerAccount", "maxAccounts", "maxFileBytesPerOrg", "maxConcurrentRunsPerOrg", "computeFuelPerOrg", "maxFuelPerDeveloperPerDay" ], "description": "The per-account limits, and the compute and file limits of each organization (or personal account) that has no override. `maxFuelPerDeveloperPerDay` (0: no limit) is a decimal string; the others are JSON numbers." }, "OrgQuotas": { "type": "object", "properties": { "maxConcurrentRuns": { "type": "integer", "format": "int64", "minimum": 0 }, "computeFuel": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "maxFileBytes": { "type": "integer", "format": "int64", "minimum": 0 } }, "description": "One payer's limits in place of the cluster's; a limit left out is the cluster's." }, "QuotaSettings": { "type": "object", "properties": { "maxAppsPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxBundleBytesPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxApiKeysPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxOrgsPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxAccounts": { "type": "integer", "format": "int64", "minimum": 0 }, "maxFileBytesPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "maxConcurrentRunsPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "computeFuelPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "maxFuelPerDeveloperPerDay": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "orgs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/OrgQuotas" } } }, "required": [ "maxAppsPerAccount", "maxBundleBytesPerAccount", "maxApiKeysPerAccount", "maxOrgsPerAccount", "maxAccounts", "maxFileBytesPerOrg", "maxConcurrentRunsPerOrg", "computeFuelPerOrg", "maxFuelPerDeveloperPerDay", "orgs" ], "description": "`GET /ops/quotas`: the cluster's limits and, under `orgs`, each payer's overrides by payer id." }, "UsageDay": { "type": "object", "properties": { "date": { "type": "string" }, "runs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "fuel": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "wallMs": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "writes": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "bytesWritten": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "events": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" } }, "required": [ "date", "runs", "fuel", "wallMs", "writes", "bytesWritten", "events" ], "description": "What an app's runs used on one UTC day (`date`, `YYYY-MM-DD`), each figure a decimal string; `wallMs` is information only." }, "RunFile": { "type": "object", "properties": { "id": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "sha256": { "type": "string" } }, "required": [ "id" ], "description": "A file a run reads or wrote: its id, and its plaintext size and SHA-256 (hex) only for a caller who may list the app's files." }, "Run": { "type": "object", "properties": { "run": { "type": "string" }, "method": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed", "cancelled" ] }, "cancelRequested": { "type": "boolean" }, "startTsMs": { "type": "integer", "format": "int64", "minimum": 0 }, "caps": { "type": "object", "properties": { "fuel": { "type": "integer", "format": "int64", "minimum": 0 }, "memoryMib": { "type": "integer", "format": "int64", "minimum": 0 }, "wallSecs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "fuel", "memoryMib", "wallSecs" ] }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/RunFile" } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "format": "int64", "minimum": 0 }, "node": { "type": "integer", "format": "int64", "minimum": 0 }, "tsMs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "attempt", "node", "tsMs" ] } }, "final": { "type": [ "object", "null" ], "properties": { "attempt": { "type": "integer", "format": "int64", "minimum": 0 }, "outcome": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "done" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "failed" ] }, "reason": { "type": "string", "enum": [ "fuel", "memory", "trap", "app-error", "integrity", "cancelled", "lost", "refused", "timeout", "quota", "not-granted", "too-large" ] } }, "required": [ "kind", "reason" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cancelled" ] } }, "required": [ "kind" ] } ], "discriminator": { "propertyName": "kind" } }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/RunFile" } }, "usage": { "type": "object", "properties": { "cpuMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "gibMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "fuel": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "cpuMicros", "gibMicros", "fuel" ] }, "tsMs": { "type": "integer", "format": "int64", "minimum": 0 }, "message": { "type": [ "string", "null" ] } }, "required": [ "attempt", "outcome", "outputs", "usage", "tsMs", "message" ] }, "progress": { "type": [ "object", "null" ], "properties": { "percent": { "type": "integer", "format": "int64", "minimum": 0 }, "step": { "type": "string" } }, "required": [ "percent", "step" ] }, "queue": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unplaced", "waiting", "granted" ] }, "capacity": { "type": "integer", "format": "int64", "minimum": 0 }, "pool": { "type": "string" }, "reason": { "type": "string", "enum": [ "NO_CAPACITY", "POOL_FULL", "PAYER_AT_RUN_QUOTA", "PAYER_AT_FUEL_QUOTA" ] } }, "required": [ "state", "capacity", "pool" ] } }, "required": [ "run", "method", "state", "cancelRequested", "startTsMs", "caps", "inputs", "attempts", "final", "progress" ], "description": "A compute run's record, without its arguments or keys: its method, state, caps (`fuel` a JSON number here), inputs, attempts (`tsMs` Unix milliseconds) and final outcome (`null` while it runs; `message` the failure text, `null` unless the caller may list the app's files). `progress` is the leader's last poll (`null` elsewhere, when it is not active, or to a caller who may not list files); `queue` where the run waits for a job node, to a caller who may list files only." }, "AccountProof": { "type": "object", "properties": { "statement": { "$ref": "#/components/schemas/AccountStatement" }, "key": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "statement", "key", "signature" ], "description": "A statement, signed with the answering node's receipt key (hex, Ed25519 over the statement's canonical JSON after its domain), that the account asked to bind `nonce` for `audience`, valid from `issuedAt` to `expiresAt` (Unix seconds)." }, "AccountStatement": { "type": "object", "properties": { "cluster": { "type": "string" }, "node": { "type": "integer", "format": "int64", "minimum": 0 }, "account": { "type": "string" }, "nonce": { "type": "string" }, "audience": { "type": "string" }, "issuedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "cluster", "node", "account", "nonce", "audience", "issuedAt", "expiresAt" ], "description": "What an account proof states: the cluster and node, the account, the nonce and audience it binds, and when it was issued and expires (Unix seconds)." }, "PackageOrigin": { "type": "object", "properties": { "package": { "type": "string" }, "origin": { "type": "string" }, "rpId": { "type": "string" }, "addedBy": { "type": "string" }, "addedAt": { "type": "string" }, "served": { "type": "boolean" } }, "required": [ "package", "origin", "rpId", "addedBy", "addedAt", "served" ], "description": "A custom frontend origin of a package: the rp-id its passkeys use, who registered it and when (RFC 3339), and whether the cluster serves the package's frontend there." }, "SignUpState": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/SignUp" }, "orgInvites": { "type": "boolean" }, "signUpInvites": { "type": "boolean" }, "inviteRequired": { "type": "boolean" } }, "required": [ "policy", "orgInvites", "signUpInvites", "inviteRequired" ], "description": "The sign-up policy and what it implies: whether organization invites and cluster sign-up invites admit a new account, and whether one is required." }, "ApprovedReleases": { "type": "object", "properties": { "approvedReleases": { "type": "array", "items": { "type": "string" } } }, "required": [ "approvedReleases" ], "description": "The mero-tee releases the scope approves now, after the change." }, "OutboundApproved": { "type": "object", "properties": { "signer": { "type": "string" }, "approval": { "$ref": "#/components/schemas/OutboundApproval" } }, "required": [ "signer", "approval" ], "description": "The outbound approval the scope holds now for the package's publisher (`signer`), after the change." }, "Uninstalled": { "type": "object", "properties": { "removed": { "type": "array", "items": { "type": "string" } } }, "required": [ "removed" ], "description": "The versions an uninstall removed." }, "Deadlines": { "type": "object", "properties": { "deadlines": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "after": { "type": "string" }, "afterSecs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "version", "after", "afterSecs" ] } } }, "required": [ "deadlines" ], "description": "Every release deadline after the change, oldest release first (`after` RFC 3339, `afterSecs` Unix seconds)." }, "SignUpSet": { "type": "object", "properties": { "governance": { "$ref": "#/components/schemas/Governance" }, "signUp": { "$ref": "#/components/schemas/SignUpState" } }, "required": [ "governance", "signUp" ], "description": "The cluster's governance and sign-up policy after the change." }, "InviteKey": { "type": "object", "properties": { "inviteKey": { "type": "string" } }, "required": [ "inviteKey" ], "description": "The key of the cluster sign-up invite withdrawn." }, "UpgradeRun": { "type": "object", "properties": { "runId": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" }, "team": { "type": "string" }, "cascade": { "type": "boolean" }, "by": { "type": "string" }, "startedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "apps": { "type": "array", "items": { "type": "string" } }, "done": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "object", "additionalProperties": true }, "finished": { "type": "boolean" } }, "required": [ "runId", "package", "version", "cascade", "by", "startedAt", "apps", "done", "failed", "finished" ], "description": "An organization-wide upgrade run: the apps it targets, those done, and why each failed one failed." }, "App": { "type": "object", "properties": { "appId": { "type": "string" }, "name": { "type": "string" }, "group": { "type": "integer", "format": "int64", "minimum": 0 }, "bundle": { "type": "string" }, "owner": { "type": "string" }, "org": { "type": [ "string", "null" ] }, "access": { "$ref": "#/components/schemas/Access" }, "confirmMethods": { "type": "array", "items": { "type": "string" } }, "executor": { "type": "string", "enum": [ "component", "wasmer" ] }, "replicas": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "createdAt": { "type": "integer", "format": "int64", "minimum": 0 }, "initArgs": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "computeBundle": { "type": "string" }, "components": { "type": "string", "enum": [ "computeOnly" ] }, "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "lastUpgrade": { "$ref": "#/components/schemas/Upgrade" }, "deployment": { "type": "string" }, "release": { "$ref": "#/components/schemas/PackageRef" }, "restore": { "type": "object", "properties": { "seed": { "type": "integer", "format": "int64", "minimum": 0 }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "sha256": { "type": "string" }, "index": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "name", "sha256", "index" ] } } } }, "required": [ "appId", "name", "group", "bundle", "owner", "org", "access", "confirmMethods", "replicas", "createdAt", "initArgs", "metadata" ], "description": "An app instance (a context) as the directory records it. `executor` is absent for an SDK 0.12 app (wasmer), which this node lists but does not run; `release` is the package release it runs, absent for a record from before or a raw upload; `restore` is a restore from a backup under way." }, "AppEntry": { "type": "object", "properties": { "appId": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "org": { "type": [ "string", "null" ] }, "bundle": { "type": "string" }, "package": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "deployment": { "type": [ "string", "null" ] } }, "required": [ "appId", "name", "owner", "org", "bundle", "package", "version" ], "description": "An app as `GET /apps` lists it: `package` and `version` name the release its bundle came from (`null` for a raw upload), `deployment` the deployment it was created from (`null` for none; absent from an older node, as 1.0.0-rc.1)." }, "PackageRef": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "service": { "type": "string" }, "compute": { "type": "boolean" } }, "required": [ "package", "version" ], "description": "One service of one package release: `service` is absent for a single-service bundle, `compute` (absent: false) marks the service's compute component." }, "Upgrade": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "at": { "type": "integer", "format": "int64", "minimum": 0 }, "by": { "type": "string" }, "ok": { "type": "boolean" }, "error": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "run": { "type": "string" }, "apiKey": { "type": "string" }, "fromRelease": { "$ref": "#/components/schemas/PackageRef" }, "toRelease": { "$ref": "#/components/schemas/PackageRef" } }, "required": [ "from", "to", "at", "by", "ok" ], "description": "The last upgrade tried on an app, done or failed: `from` and `to` are bundle hashes, `by` the account (or `operator`), `run` the organization-wide run it was part of, `apiKey` the upgrade key that made it." }, "Package": { "type": "object", "properties": { "package": { "type": "string" }, "signerId": { "type": "string" }, "owner": { "type": "string" }, "latest": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "mpk": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "source": { "type": "string", "enum": [ "registry", "upload" ] }, "services": { "type": "object", "additionalProperties": { "type": "string" } }, "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "outbound": { "type": "array", "items": { "type": "string" } }, "installedBy": { "type": "string" }, "installedAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "version", "mpk", "size", "source", "services", "metadata", "outbound", "installedBy", "installedAt" ] } } }, "required": [ "package", "signerId", "owner", "latest", "versions" ], "description": "A package and the releases of it the caller may see, oldest first; `latest` is the newest of those." }, "ApiKey": { "type": "object", "properties": { "keyId": { "type": "string" }, "account": { "type": "string" }, "label": { "type": "string" }, "apps": { "type": [ "array", "null" ], "items": { "type": "string" } }, "methods": { "type": [ "array", "null" ], "items": { "type": "string" } }, "readOnly": { "type": "boolean" }, "allowConfirm": { "type": "boolean" }, "expiresAt": { "type": "integer", "format": "int64", "minimum": 0 }, "upgrades": { "type": "object", "properties": { "app": { "type": "string" }, "package": { "type": "string" }, "signer": { "type": "string" }, "proofKey": { "type": "string" } }, "required": [ "app", "package", "signer", "proofKey" ] } }, "required": [ "keyId", "account", "label", "apps", "methods", "readOnly", "allowConfirm", "expiresAt" ], "description": "An API key as the account's list shows it (never its secret): `apps` and `methods` are `null` for every one; `upgrades` makes it an upgrade key." }, "Org": { "type": "object", "properties": { "orgId": { "type": "string" }, "name": { "type": "string" }, "members": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/OrgRole" } }, "teams": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Team" } }, "defaultCapabilities": { "type": "integer", "format": "int64", "minimum": 0 }, "capabilities": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 } }, "approvedReleases": { "type": "array", "items": { "type": "string" } }, "outboundApprovals": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/OutboundApproval" } }, "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "memberMetadata": { "type": "object", "additionalProperties": true }, "upgradeRuns": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UpgradeRun" } }, "recovery": { "type": "object", "properties": { "publicKey": { "type": "string" }, "setAt": { "type": "integer", "format": "int64", "minimum": 0 }, "pending": { "type": [ "object", "null" ], "properties": { "account": { "type": "string" }, "startedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "readyAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "account", "startedAt", "readyAt" ] } }, "required": [ "publicKey", "setAt", "pending" ] }, "allApps": { "type": "array", "items": { "type": "string" } }, "personal": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "legacy", "standalone", "shared" ] }, "releaseApprovers": { "type": "array", "items": { "type": "string" } }, "publishes": { "type": "array", "items": { "type": "string" } }, "newWorkStopped": { "type": [ "object", "null" ], "properties": { "release": { "type": "string" }, "after": { "type": "string" } }, "required": [ "release", "after" ] } }, "required": [ "orgId", "name", "members", "teams", "defaultCapabilities", "capabilities", "approvedReleases", "outboundApprovals", "metadata", "memberMetadata", "upgradeRuns" ], "description": "An organization as `GET /orgs/{org}` answers it. `members` maps each account to its role, `capabilities` and `defaultCapabilities` are capability bits, `outboundApprovals` is keyed by package signer, `upgradeRuns` by run id; `recovery` is absent when the organization set no recovery key, `allApps` when no member gets every app added later, `personal` unless it is its owner's personal organization (where instances created without naming an organization go)." }, "Team": { "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "parent": { "type": [ "string", "null" ] }, "join": { "$ref": "#/components/schemas/TeamJoin" }, "members": { "type": "object", "additionalProperties": { "type": "boolean" } }, "readOnly": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64", "minimum": 0 } }, "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "removed": { "type": "array", "items": { "type": "string" } }, "defaultCapabilities": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "teamId", "name", "parent", "join", "members", "readOnly", "capabilities", "metadata", "removed" ], "description": "A team as its organization records it: `members` maps each direct row to whether it is a lead; `capabilities` are capability bits per row; `defaultCapabilities` is absent when unset." }, "TeamView": { "type": "object", "properties": { "teamId": { "type": "string" }, "name": { "type": "string" }, "parent": { "type": [ "string", "null" ] }, "join": { "$ref": "#/components/schemas/TeamJoin" }, "metadata": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "package": { "type": [ "string", "null" ] }, "defaultCapabilities": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "members": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "role": { "$ref": "#/components/schemas/TeamRole" }, "capabilities": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "account", "role", "capabilities" ] } }, "children": { "type": "array", "items": { "type": "string" } }, "apps": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string" }, "name": { "type": "string" }, "contextId": { "type": "string" } }, "required": [ "appId", "name", "contextId" ] } }, "myRole": { "anyOf": [ { "$ref": "#/components/schemas/TeamRole" }, { "type": "null" } ] }, "member": { "type": "boolean" } }, "required": [ "teamId", "name", "parent", "join", "metadata", "members", "children", "apps", "myRole", "member" ], "description": "A team as `GET /orgs/{org}/teams/{team}` answers it: each member's row, the child teams the caller sees, its apps, and the caller's own row (`myRole`, `null` for none) and membership (`member`). `package` names the package of an app team; it and `defaultCapabilities` are absent from an older node (1.0.0-rc.1 sends neither)." }, "Deployment": { "type": "object", "properties": { "id": { "type": "string" }, "host": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "owner": { "$ref": "#/components/schemas/Deployer" }, "apps": { "type": "array", "items": { "type": "object", "properties": { "app": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" }, "addedBy": { "type": "string" }, "addedAt": { "type": "string" } }, "required": [ "app", "package", "version", "addedBy", "addedAt" ] } }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "host", "name", "owner", "apps", "createdBy", "createdAt" ], "description": "A deployment as its managers list it. `host` is its frontend host, `null` on a node with no apps domain; times are RFC 3339." }, "DeadLetter": { "type": "object", "properties": { "seq": { "type": "integer", "format": "int64", "minimum": 0 }, "app": { "type": "string" }, "method": { "type": "string" }, "reason": { "type": "string" }, "atMs": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "seq", "app", "method", "reason", "atMs" ], "description": "A cross-app call that was never delivered: its sequence number, the target app and method, why, and when (`atMs`, Unix milliseconds)." }, "Governance": { "type": "object", "properties": { "releases": { "type": "string", "enum": [ "owner", "operator" ] }, "appUpgrades": { "type": "string", "enum": [ "owner", "operator" ] }, "outbound": { "type": "string", "enum": [ "owner", "operator" ] }, "deployments": { "type": "string", "enum": [ "granted", "open" ] }, "deployers": { "type": "string", "enum": [ "owner", "operator" ] }, "signUp": { "type": "string", "enum": [ "invite", "closed", "open" ] } }, "required": [ "releases", "appUpgrades", "outbound" ], "description": "Who decides what on this cluster: release approvals, app upgrades and outbound approvals (`owner`: each app's owner; `operator`: the operator), and, left out at their defaults, `deployments` (`open`), `deployers` (`operator`) and `signUp` (`open`)." }, "OutboundApproval": { "type": "object", "properties": { "prefixes": { "type": "array", "items": { "type": "string" } }, "reviewed": { "type": "array", "items": { "type": "string" } } }, "required": [ "prefixes", "reviewed" ], "description": "What an owner approved for one publisher's apps to call out to: the approved URL prefixes, and every prefix it was shown." }, "AppScope": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "org" ] }, "org": { "type": "string" }, "personal": { "type": "boolean" } }, "required": [ "kind", "org" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "account" ] } }, "required": [ "kind" ] } ], "discriminator": { "propertyName": "kind" }, "description": "The scope whose approvals cover an app: its organization (`personal: true` when it is its owner's personal organization). `account` is only `GET /auth/apps`' own scope: the apps the account owns, wherever they are." }, "ClusterRelease": { "type": "object", "properties": { "release": { "type": "string" }, "nodes": { "type": "integer", "format": "int64", "minimum": 0 }, "approved": { "type": "boolean" } }, "required": [ "release", "nodes", "approved" ], "description": "A mero-tee release the cluster's nodes run: how many run it, and whether the scope approved it (`true` where nothing was ever recorded)." }, "BundleRelease": { "type": "object", "properties": { "bundle": { "type": "string" }, "package": { "type": "string" }, "version": { "type": "string" } }, "required": [ "bundle" ], "description": "A bundle by its digest, with the release it came from where the reader may see it." }, "ReportUpgrade": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/BundleRelease" }, "to": { "$ref": "#/components/schemas/BundleRelease" }, "at": { "type": "integer", "format": "int64", "minimum": 0 }, "ok": { "type": "boolean" }, "actorKind": { "type": "string", "enum": [ "owner", "member", "operator" ] }, "actor": { "type": "string" }, "error": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "run": { "type": "string" }, "apiKey": { "type": "string" } }, "required": [ "from", "to", "at", "ok", "actorKind" ], "description": "An app's last upgrade as a report shows it. `actor`, `error`, `run` and `apiKey` are shown to the app's people, never to the operator." }, "ReportApp": { "type": "object", "properties": { "app": { "type": "string" }, "group": { "type": "integer", "format": "int64", "minimum": 0 }, "scope": { "$ref": "#/components/schemas/AppScope" }, "bundle": { "type": "string" }, "package": { "type": [ "object", "null" ], "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "service": { "type": [ "string", "null" ] } }, "required": [ "package", "version" ] }, "publisher": { "type": [ "object", "null" ], "properties": { "signer": { "type": "string" }, "org": { "type": [ "string", "null" ] } }, "required": [ "signer", "org" ] }, "upgradesHeldBy": { "type": "string", "enum": [ "operator", "owner", "publisher" ] }, "releasesApprovedBy": { "type": "string", "enum": [ "operator", "publisher", "owner" ] }, "lastUpgrade": { "anyOf": [ { "$ref": "#/components/schemas/ReportUpgrade" }, { "type": "null" } ] }, "approvedReleases": { "type": [ "array", "null" ], "items": { "type": "string" } }, "replicas": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "release": { "type": [ "string", "null" ] }, "approved": { "type": "boolean" } }, "required": [ "node", "release", "approved" ] } }, "lastWriteAt": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "name": { "type": "string" }, "team": { "type": "string" }, "availableVersions": { "type": "array", "items": { "type": "string" } }, "latestReachable": { "type": [ "string", "null" ] }, "latestBlocked": { "type": "object", "properties": { "version": { "type": "string" }, "reason": { "type": "string", "enum": [ "authority", "runtime" ] }, "message": { "type": "string" }, "minRuntimeVersion": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "integer", "format": "int64", "minimum": 0 }, "runtime": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "before": { "type": "string" } }, "required": [ "before" ] }, { "type": "null" } ] } }, "required": [ "node", "runtime" ] } } }, "required": [ "version", "reason", "message" ] } }, "required": [ "app", "group", "scope", "bundle", "package", "publisher", "upgradesHeldBy", "releasesApprovedBy", "lastUpgrade", "approvedReleases", "replicas", "lastWriteAt" ], "description": "One app in a release report (`GET /auth/apps`, `GET /orgs/{org}/apps`, `GET /ops/apps`): its bundle and release (`package`, `null` where the reader may not see it), the publisher's key and bound organization, who holds its upgrades and release approvals, its last upgrade, the releases approved to hold it (`null`: unrestricted), each replica's release, and `lastWriteAt` (Unix seconds, `null` when unknown). `name`, `team`, `availableVersions` (newer releases, oldest first), `latestReachable` and `latestBlocked` (the newest release and why an upgrade would not take it) are for the app's people, never the operator." }, "DeploymentRecord": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "$ref": "#/components/schemas/Deployer" }, "apps": { "type": "object", "additionalProperties": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": "string" }, "addedBy": { "type": "string" }, "addedAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "package", "version", "addedBy", "addedAt" ] } }, "createdBy": { "type": "string" }, "createdAt": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "id", "name", "owner", "apps", "createdBy", "createdAt" ], "description": "A deployment as the directory records it: the release it offers by app name (`addedAt` Unix seconds), who created it and when (Unix seconds)." }, "DeployerGrant": { "type": "object", "properties": { "until": { "type": "integer", "format": "int64", "minimum": 0 }, "grantedAt": { "type": "integer", "format": "int64", "minimum": 0 }, "grantedBy": { "type": "string" } }, "required": [ "grantedAt", "grantedBy" ], "description": "A grant to install where deployments are granted: until when (Unix seconds; absent: it does not end), when and by whom it was granted." }, "SignUpInvite": { "type": "object", "properties": { "inviteKey": { "type": "string" }, "uses": { "type": "integer", "format": "int64", "minimum": 0 }, "expiresAt": { "type": "string" }, "expiresAtSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "inviteKey", "uses", "expiresAt", "expiresAtSecs", "createdBy", "createdAt" ], "description": "A cluster sign-up invite, never its token: uses left, when it expires (`expiresAt` RFC 3339, `expiresAtSecs` Unix seconds), who made it and when (RFC 3339)." }, "ProofOnly": { "type": "object", "properties": { "operatorProof": { "$ref": "#/components/schemas/OperatorProof" } }, "description": "What an operator decision that names nothing in its body may carry: none at first, the operator's proof after the `428`.", "additionalProperties": false }, "ConfirmOnly": { "type": "object", "properties": { "confirm": { "$ref": "#/components/schemas/Confirm" } }, "description": "The body of a step-up that names nothing else: none (or `{}`) at first, the passkey assertion after the `412`." }, "QuotaChanges": { "type": "object", "properties": { "org": { "type": "string" }, "operatorProof": { "$ref": "#/components/schemas/OperatorProof" }, "orgs": { "description": "Free-form JSON: its shape is not this API's (see the description around it for whose it is)." }, "maxAppsPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxBundleBytesPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxApiKeysPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxOrgsPerAccount": { "type": "integer", "format": "int64", "minimum": 0 }, "maxAccounts": { "type": "integer", "format": "int64", "minimum": 0 }, "maxFileBytesPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "maxConcurrentRunsPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "computeFuelPerOrg": { "type": "integer", "format": "int64", "minimum": 0 }, "maxFuelPerDeveloperPerDay": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "maxConcurrentRuns": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "computeFuel": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)$", "description": "an unsigned 64-bit integer as a decimal string (D20)" }, "maxFileBytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, "description": "The limits `POST /ops/quotas` changes, each optional: without `org`, the cluster's (those `GET /ops/quotas` answers, `maxFuelPerDeveloperPerDay` a decimal string); with `org`, one payer's (`maxConcurrentRuns`, `computeFuel` a decimal string, `maxFileBytes`; `null` clears one). `orgs` is ignored. Any other property is refused `400 UNKNOWN_QUOTA`.", "additionalProperties": false } }, "securitySchemes": { "session": { "type": "http", "scheme": "bearer", "bearerFormat": "v2..", "description": "A passkey session's token (15 minutes, by the issuing node), from a passkey ceremony or `/auth/refresh`." }, "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "cal_...", "description": "An API key from `POST /auth/apikeys`, scoped to apps, methods and read-only as made." }, "opsToken": { "type": "http", "scheme": "bearer", "description": "The node's ops token (`--ops-token` / `--ops-token-sha256`)." } } } }