{ "openapi": "3.1.0", "info": { "title": "SyncPilled API", "version": "0.1.0", "description": "Offline-first data sync for iOS and Android apps. Errors are `{ \"error\": { \"code\", \"message\" } }`." }, "servers": [ { "url": "https://api.syncpilled.com", "description": "The hosted API. On a self-hosted deployment, use your own origin." } ], "tags": [ { "name": "Operations", "description": "Service health." }, { "name": "Sign-in", "description": "Exchanging the app's sign-in token for a SyncPilled token." }, { "name": "Sync", "description": "Pushing and pulling records." }, { "name": "Files", "description": "Files by content hash, private to the person who uploaded them." }, { "name": "Account", "description": "The person's own account: export and deletion." }, { "name": "Export", "description": "Every person's records, for the developer." }, { "name": "Your account", "description": "Who is signed in to manage apps, and which account they act on." }, { "name": "Apps", "description": "Your apps and their settings." }, { "name": "People", "description": "Who uses an app, and how much they store: counts only." }, { "name": "Members", "description": "Who else manages the account, and invitations, on the hosted version." }, { "name": "CLI", "description": "Logging the CLI in, approved by a person in the hosted console." }, { "name": "Management keys", "description": "Keys for the CLI, CI and agents, made in the console." } ], "components": { "securitySchemes": { "IssuerToken": { "type": "http", "scheme": "bearer", "description": "A token from the app's own sign-in provider, such as a Firebase ID token." }, "SyncToken": { "type": "http", "scheme": "bearer", "description": "A SyncPilled token from `POST /v1/apps/{app}/auth/token`, valid for one hour." }, "AppAdminKey": { "type": "http", "scheme": "bearer", "bearerFormat": "spk_admin_…", "description": "The app's admin key." }, "ManagementKey": { "type": "http", "scheme": "bearer", "bearerFormat": "spk_mgmt_…", "description": "A management key, made in the console. It acts as an admin of its account." }, "ConsoleSession": { "type": "apiKey", "in": "cookie", "name": "sp_identity_auth.session_token", "description": "The hosted console's session, or Cloudflare Access's CF_Authorization on a self-hosted one. Such requests also send x-console-request: 1." } }, "schemas": {}, "parameters": {} }, "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "Operations" ], "summary": "Check the Worker is up", "responses": { "200": { "description": "The Worker is accepting requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "version": { "type": "string" } }, "required": [ "ok", "version" ] } } } } } } }, "/v1/console/capabilities": { "get": { "operationId": "getConsoleCapabilities", "tags": [ "Operations" ], "summary": "How the console signs people in here", "responses": { "200": { "description": "The deployment's sign-in.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "cloudflare_access", "hosted" ], "description": "How this deployment signs people in to the console." }, "google": { "type": "boolean", "description": "Whether the hosted console offers Google sign-in." } }, "required": [ "mode", "google" ] } } } } } } }, "/v1/apps/{app}/auth/token": { "post": { "operationId": "exchangeToken", "tags": [ "Sign-in" ], "summary": "Exchange the app's sign-in token for a SyncPilled token", "description": "Send the token from the app's own sign-in provider (Firebase, Supabase, Auth0, Clerk, Sign in with Apple, any JWKS) as `Authorization: Bearer `. The answer is a SyncPilled token for one hour.", "security": [ { "IssuerToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "200": { "description": "A SyncPilled token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Send it as `Authorization: Bearer ` to every other app route." }, "expires_at": { "type": "string", "format": "date-time", "description": "One hour after it was issued." }, "user_id": { "type": "string", "description": "The person the app's sign-in token names." } }, "required": [ "token", "expires_at", "user_id" ] } } } }, "401": { "description": "`auth_required`: no sign-in token, or one that did not verify for this app.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`account_deleted`: the person deleted their account. Stop syncing and erase the local copy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "`rate_limited`: too many requests. Wait as many seconds as `Retry-After` says, then try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "`issuer_unavailable`: the sign-in provider's keys could not be fetched. Retry with backoff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{app}/sync/push": { "post": { "operationId": "pushChanges", "tags": [ "Sync" ], "summary": "Upload a batch of changes", "description": "At most 500 changes and 5242880 bytes. Per record, the latest `changed_at` wins; a time ahead of the server's is capped at it, and a tie keeps the change that arrived first. A change dated by the device rather than by the record (a deletion, say) must keep its `changed_at` when it is sent again.", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "changes": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "collection": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "changed_at": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean", "enum": [ false ] }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "collection", "id", "changed_at", "data" ], "description": "A record's whole data." }, { "type": "object", "properties": { "collection": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "changed_at": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "collection", "id", "changed_at", "deleted" ], "additionalProperties": false, "description": "A deletion, without data." } ] }, "minItems": 1, "maxItems": 500 } }, "required": [ "changes" ] } } } }, "responses": { "200": { "description": "One result per change, in order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "applied" ] }, "seq": { "type": "integer" } }, "required": [ "status", "seq" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ignored" ] }, "seq": { "type": "integer" }, "current": { "anyOf": [ { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "collection", "id", "seq", "changed_at", "data" ] }, { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "collection", "id", "seq", "changed_at", "deleted" ] } ], "description": "The stored version that beat the change; the device adopts it." } }, "required": [ "status", "seq", "current" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "refused" ] }, "code": { "type": "string", "description": "Why: `quota_exceeded` (the app's limit on one person's records) or `storage_full`. Codes may be added; treat any as a refusal." } }, "required": [ "status", "code" ], "description": "A change that would grow the person's records past a limit, not stored. Keep it, and send it again later with the same `changed_at`. Deletions are never refused." } ] }, "description": "One result per change, in order. Fewer results than changes means the answer would have been too large: send the rest again." } }, "required": [ "results" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`account_deleted`: the person deleted their account. Stop syncing and erase the local copy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "`payload_too_large`: the push, or one record's data, is larger than allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "`rate_limited`: too many requests. Wait as many seconds as `Retry-After` says, then try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{app}/sync/pull": { "get": { "operationId": "pullChanges", "tags": [ "Sync" ], "summary": "Download the changes after a position", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of changes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "epoch": { "type": "string", "description": "Names the person's store. When it changes, positions from before mean nothing: start over from 0." }, "changes": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "collection", "id", "seq", "changed_at", "data" ] }, { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "collection", "id", "seq", "changed_at", "deleted" ] } ] }, "description": "Oldest first, each record once, in its latest state." }, "next": { "type": "integer", "description": "The position to pull after next time." }, "has_more": { "type": "boolean" } }, "required": [ "epoch", "changes", "next", "has_more" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`account_deleted`: the person deleted their account. Stop syncing and erase the local copy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "`rate_limited`: too many requests. Wait as many seconds as `Retry-After` says, then try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{app}/files/{sha256}": { "head": { "operationId": "checkFile", "tags": [ "Files" ], "summary": "Check whether a file is stored", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The lowercase hex SHA-256 of the file's bytes." }, "required": true, "description": "The lowercase hex SHA-256 of the file's bytes.", "name": "sha256", "in": "path" } ], "responses": { "200": { "description": "The file is stored." }, "400": { "description": "`validation_error`: the request does not match this operation." }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again." }, "404": { "description": "The app does not exist, or the person has no such file." } } }, "get": { "operationId": "getFile", "tags": [ "Files" ], "summary": "Download a file", "description": "Files are private to the person who uploaded them.", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The lowercase hex SHA-256 of the file's bytes." }, "required": true, "description": "The lowercase hex SHA-256 of the file's bytes.", "name": "sha256", "in": "path" } ], "responses": { "200": { "description": "The file's bytes, with the media type it was uploaded with.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such app, or no such file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "put": { "operationId": "putFile", "tags": [ "Files" ], "summary": "Upload a file", "description": "The body is the file's bytes, with its media type as `Content-Type`, up to the app's file size limit. Upload a file before the record that names it.", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The lowercase hex SHA-256 of the file's bytes." }, "required": true, "description": "The lowercase hex SHA-256 of the file's bytes.", "name": "sha256", "in": "path" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The file was already stored." }, "201": { "description": "The file is stored." }, "400": { "description": "`validation_error`: the bytes do not hash to the name, or `Content-Type` is not a media type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`account_deleted`: the person deleted their account. Stop syncing and erase the local copy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "413": { "description": "`payload_too_large`: larger than the app's file size limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "`rate_limited`: too many requests. Wait as many seconds as `Retry-After` says, then try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "507": { "description": "`quota_exceeded`: the person's files have reached the app's limit, or `storage_full`. Not stored; hold back the records that name the file, and upload it again later. Deleting files frees space.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Delete a file", "description": "Answers 204 whether or not the file was stored.", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "The lowercase hex SHA-256 of the file's bytes." }, "required": true, "description": "The lowercase hex SHA-256 of the file's bytes.", "name": "sha256", "in": "path" } ], "responses": { "204": { "description": "The file is not stored." }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{app}/me": { "delete": { "operationId": "deleteMe", "tags": [ "Account" ], "summary": "Delete the person's account in the app, for good", "description": "Deletes their records, past versions and files. From then on their pushes, pulls, uploads and new sign-ins answer 403 `account_deleted`. Repeating the deletion after a failure partway finishes it.", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "200": { "description": "What was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "object", "properties": { "records": { "type": "integer" }, "files": { "type": "integer" } }, "required": [ "records", "files" ] } }, "required": [ "deleted" ] } } } }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{app}/me/export": { "get": { "operationId": "exportMe", "tags": [ "Account" ], "summary": "Export the person's current records", "description": "For access requests. Deletions are left out.", "security": [ { "SyncToken": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "200": { "description": "One record per line.", "content": { "application/x-ndjson": { "schema": { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "collection", "id", "seq", "changed_at", "data" ] } } } }, "401": { "description": "`auth_required`: no SyncPilled token, or one that expired or belongs to another app. Sign in again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/apps/{app}/export": { "get": { "operationId": "exportApp", "tags": [ "Export" ], "summary": "Export every person's current records in the app", "description": "Needs the app's admin key as `Authorization: Bearer `. Deletions are left out.", "security": [ { "AppAdminKey": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "200": { "description": "One record per line, each with its `user_id`.", "content": { "application/x-ndjson": { "schema": { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": {} }, "user_id": { "type": "string" } }, "required": [ "collection", "id", "seq", "changed_at", "data", "user_id" ] } } } }, "401": { "description": "`auth_required`: no admin key, or not this app's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/session": { "get": { "operationId": "getSession", "tags": [ "Your account" ], "summary": "Who is calling, and for which account", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "responses": { "200": { "description": "The caller and their account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "cloudflare_access", "hosted" ], "description": "How this deployment signs people in." }, "via": { "type": "string", "enum": [ "session", "access", "key" ], "description": "How this caller signed in: the hosted console, Cloudflare Access, or a management key." }, "user": { "type": [ "object", "null" ], "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" } }, "required": [ "email", "name", "email_verified" ], "description": "The person, for a hosted sign-in; null for Cloudflare Access and keys." }, "email": { "type": [ "string", "null" ], "description": "Who signed in, where known." }, "organization": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "The account this request acts on; null for someone invited who has not accepted yet." }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", null ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "id", "name", "role" ] }, "description": "Every account the person belongs to; only the current one for keys and Cloudflare Access." } }, "required": [ "mode", "via", "user", "email", "organization", "role", "organizations" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/organizations/select": { "post": { "operationId": "selectOrganization", "tags": [ "Your account" ], "summary": "Switch to another account the person belongs to", "description": "Hosted console only; remembered in a cookie.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": "string", "minLength": 1 } }, "required": [ "organization_id" ] } } } }, "responses": { "200": { "description": "The caller, now acting on that account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "cloudflare_access", "hosted" ], "description": "How this deployment signs people in." }, "via": { "type": "string", "enum": [ "session", "access", "key" ], "description": "How this caller signed in: the hosted console, Cloudflare Access, or a management key." }, "user": { "type": [ "object", "null" ], "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" } }, "required": [ "email", "name", "email_verified" ], "description": "The person, for a hosted sign-in; null for Cloudflare Access and keys." }, "email": { "type": [ "string", "null" ], "description": "Who signed in, where known." }, "organization": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "The account this request acts on; null for someone invited who has not accepted yet." }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", null ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "id", "name", "role" ] }, "description": "Every account the person belongs to; only the current one for keys and Cloudflare Access." } }, "required": [ "mode", "via", "user", "email", "organization", "role", "organizations" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/keys": { "get": { "operationId": "listKeys", "tags": [ "Management keys" ], "summary": "List the account's management keys", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "responses": { "200": { "description": "Every key, revoked ones included.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "hint": { "type": "string", "description": "The key's last four characters." }, "source": { "type": "string", "description": "Where it was made: `console` or `cli`." }, "created_at": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "label", "hint", "source", "created_at", "revoked_at" ] } } }, "required": [ "keys" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createKey", "tags": [ "Management keys" ], "summary": "Create a management key", "description": "For the CLI, CI and agents. A key acts as an admin of the account. Only an owner or admin signed in to the console may create one.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "What the key is for, such as `GitHub Actions`." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "The key, with its token shown this once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "hint": { "type": "string", "description": "The key's last four characters." }, "source": { "type": "string", "description": "Where it was made: `console` or `cli`." }, "created_at": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "label", "hint", "source", "created_at", "revoked_at" ] }, "token": { "type": "string", "description": "The key itself, shown this once and never again. Send it as `Authorization: Bearer `." } }, "required": [ "key", "token" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/keys/{key}/revoke": { "post": { "operationId": "revokeKey", "tags": [ "Management keys" ], "summary": "Revoke a management key", "description": "Only an owner or admin signed in to the console may revoke one. Revoking a revoked key changes nothing.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The key's id." }, "required": true, "description": "The key's id.", "name": "key", "in": "path" } ], "responses": { "200": { "description": "The key, revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "hint": { "type": "string", "description": "The key's last four characters." }, "source": { "type": "string", "description": "Where it was made: `console` or `cli`." }, "created_at": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "label", "hint", "source", "created_at", "revoked_at" ] } }, "required": [ "key" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such key in this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/apps": { "get": { "operationId": "listApps", "tags": [ "Apps" ], "summary": "List the account's apps", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "responses": { "200": { "description": "Every app, oldest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Generated from the name, with a random suffix; fixed for good." }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "sign_in": { "type": "object", "properties": { "issuer": { "type": "string" }, "audience": { "type": "string" }, "jwks_url": { "type": "string" }, "allow_anonymous": { "type": "boolean" } }, "required": [ "issuer", "audience", "jwks_url", "allow_anonymous" ] }, "collections": { "type": [ "array", "null" ], "items": { "type": "string" } }, "limits": { "type": "object", "properties": { "record_bytes": { "type": "integer" }, "file_bytes": { "type": "integer" }, "person_record_bytes": { "type": [ "integer", "null" ] }, "person_file_bytes": { "type": [ "integer", "null" ] } }, "required": [ "record_bytes", "file_bytes", "person_record_bytes", "person_file_bytes" ] } }, "required": [ "id", "name", "created_at", "sign_in", "collections", "limits" ] } } }, "required": [ "apps" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createApp", "tags": [ "Apps" ], "summary": "Add an app", "description": "Its people sign in with the provider named in `sign_in`. Collections and per-person limits are refused one change at a time, which SyncPilled's Swift package 0.2 and later handle; set them only once the app's clients do.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "sign_in": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "firebase" ] }, "project_id": { "type": "string", "pattern": "^[a-z0-9-]{4,40}$/u" } }, "required": [ "provider", "project_id" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "supabase" ] }, "project_ref": { "type": "string", "pattern": "^[a-z0-9]{10,40}$/u" } }, "required": [ "provider", "project_ref" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "auth0" ] }, "domain": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$/u" }, "audience": { "type": "string", "minLength": 1, "description": "Your Auth0 API's identifier." } }, "required": [ "provider", "domain", "audience" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "clerk" ] }, "frontend_api": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$/u", "description": "Your Clerk Frontend API, such as clerk.example.com." } }, "required": [ "provider", "frontend_api" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "apple" ] }, "bundle_id": { "type": "string", "pattern": "^[A-Za-z0-9.-]+$/u", "description": "Sign in with Apple's identity token names your app's bundle id as its audience." } }, "required": [ "provider", "bundle_id" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom" ] }, "issuer": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "description": "Checked against the token's `aud`; empty to accept any." }, "jwks_url": { "type": "string", "format": "uri" } }, "required": [ "provider", "issuer", "audience", "jwks_url" ] } ] }, "allow_anonymous": { "type": "boolean", "description": "Whether the provider's anonymous accounts may sync. Default true." }, "collections": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "maxItems": 200, "description": "The collections devices may push to; null for any. Others are refused one by one." }, "limits": { "type": "object", "properties": { "record_bytes": { "type": "integer", "minimum": 1, "maximum": 1048576, "description": "The largest record." }, "file_bytes": { "type": "integer", "minimum": 1, "maximum": 26214400, "description": "The largest file." }, "person_record_bytes": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many bytes of current records one person may keep; null for no limit." }, "person_file_bytes": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many bytes of files one person may keep; null for no limit." } } } }, "required": [ "name", "sign_in" ] } } } }, "responses": { "201": { "description": "The app.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Generated from the name, with a random suffix; fixed for good." }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "sign_in": { "type": "object", "properties": { "issuer": { "type": "string" }, "audience": { "type": "string" }, "jwks_url": { "type": "string" }, "allow_anonymous": { "type": "boolean" } }, "required": [ "issuer", "audience", "jwks_url", "allow_anonymous" ] }, "collections": { "type": [ "array", "null" ], "items": { "type": "string" } }, "limits": { "type": "object", "properties": { "record_bytes": { "type": "integer" }, "file_bytes": { "type": "integer" }, "person_record_bytes": { "type": [ "integer", "null" ] }, "person_file_bytes": { "type": [ "integer", "null" ] } }, "required": [ "record_bytes", "file_bytes", "person_record_bytes", "person_file_bytes" ] } }, "required": [ "id", "name", "created_at", "sign_in", "collections", "limits" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/apps/{app}": { "get": { "operationId": "getApp", "tags": [ "Apps" ], "summary": "Get an app", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "200": { "description": "The app.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Generated from the name, with a random suffix; fixed for good." }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "sign_in": { "type": "object", "properties": { "issuer": { "type": "string" }, "audience": { "type": "string" }, "jwks_url": { "type": "string" }, "allow_anonymous": { "type": "boolean" } }, "required": [ "issuer", "audience", "jwks_url", "allow_anonymous" ] }, "collections": { "type": [ "array", "null" ], "items": { "type": "string" } }, "limits": { "type": "object", "properties": { "record_bytes": { "type": "integer" }, "file_bytes": { "type": "integer" }, "person_record_bytes": { "type": [ "integer", "null" ] }, "person_file_bytes": { "type": [ "integer", "null" ] } }, "required": [ "record_bytes", "file_bytes", "person_record_bytes", "person_file_bytes" ] } }, "required": [ "id", "name", "created_at", "sign_in", "collections", "limits" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateApp", "tags": [ "Apps" ], "summary": "Change an app's settings", "description": "Only the fields sent change. Devices see a change within a minute.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "sign_in": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "firebase" ] }, "project_id": { "type": "string", "pattern": "^[a-z0-9-]{4,40}$/u" } }, "required": [ "provider", "project_id" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "supabase" ] }, "project_ref": { "type": "string", "pattern": "^[a-z0-9]{10,40}$/u" } }, "required": [ "provider", "project_ref" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "auth0" ] }, "domain": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$/u" }, "audience": { "type": "string", "minLength": 1, "description": "Your Auth0 API's identifier." } }, "required": [ "provider", "domain", "audience" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "clerk" ] }, "frontend_api": { "type": "string", "pattern": "^[a-z0-9.-]+\\.[a-z]{2,}$/u", "description": "Your Clerk Frontend API, such as clerk.example.com." } }, "required": [ "provider", "frontend_api" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "apple" ] }, "bundle_id": { "type": "string", "pattern": "^[A-Za-z0-9.-]+$/u", "description": "Sign in with Apple's identity token names your app's bundle id as its audience." } }, "required": [ "provider", "bundle_id" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom" ] }, "issuer": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "description": "Checked against the token's `aud`; empty to accept any." }, "jwks_url": { "type": "string", "format": "uri" } }, "required": [ "provider", "issuer", "audience", "jwks_url" ] } ] }, "allow_anonymous": { "type": "boolean", "description": "Whether the provider's anonymous accounts may sync. Default true." }, "collections": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "maxItems": 200, "description": "The collections devices may push to; null for any. Others are refused one by one." }, "limits": { "type": "object", "properties": { "record_bytes": { "type": "integer", "minimum": 1, "maximum": 1048576, "description": "The largest record." }, "file_bytes": { "type": "integer", "minimum": 1, "maximum": 26214400, "description": "The largest file." }, "person_record_bytes": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many bytes of current records one person may keep; null for no limit." }, "person_file_bytes": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many bytes of files one person may keep; null for no limit." } } } } } } } }, "responses": { "200": { "description": "The app as it is now.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Generated from the name, with a random suffix; fixed for good." }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "sign_in": { "type": "object", "properties": { "issuer": { "type": "string" }, "audience": { "type": "string" }, "jwks_url": { "type": "string" }, "allow_anonymous": { "type": "boolean" } }, "required": [ "issuer", "audience", "jwks_url", "allow_anonymous" ] }, "collections": { "type": [ "array", "null" ], "items": { "type": "string" } }, "limits": { "type": "object", "properties": { "record_bytes": { "type": "integer" }, "file_bytes": { "type": "integer" }, "person_record_bytes": { "type": [ "integer", "null" ] }, "person_file_bytes": { "type": [ "integer", "null" ] } }, "required": [ "record_bytes", "file_bytes", "person_record_bytes", "person_file_bytes" ] } }, "required": [ "id", "name", "created_at", "sign_in", "collections", "limits" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteApp", "tags": [ "Apps" ], "summary": "Delete an app and every person's data in it", "description": "For good. The app answers as missing at once; its people's records and files are erased within about an hour.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "202": { "description": "Being deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "erased_by": { "type": "string", "format": "date-time", "description": "About when every person's data will have been erased." } }, "required": [ "deleted", "erased_by" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/apps/{app}/stats": { "get": { "operationId": "getAppStats", "tags": [ "People" ], "summary": "Counts for an app: people, activity and storage", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "200": { "description": "The counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "integer", "description": "Everyone with an account in the app." }, "active": { "type": "object", "properties": { "day": { "type": "integer" }, "week": { "type": "integer" }, "month": { "type": "integer" } }, "required": [ "day", "week", "month" ], "description": "People who signed in within the last 1, 7 and 30 days." }, "deleted_accounts": { "type": "integer" }, "records": { "type": "integer" }, "record_bytes": { "type": "integer" }, "file_bytes": { "type": "integer" }, "measured_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Records and storage are as each person's store last reported them, after a sign-in: the oldest such report." } }, "required": [ "people", "active", "deleted_accounts", "records", "record_bytes", "file_bytes", "measured_at" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/apps/{app}/users": { "get": { "operationId": "listPeople", "tags": [ "People" ], "summary": "List an app's people", "description": "Counts only, never what they stored. In order of their ids.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "description": "The `next` of the previous page." }, "required": false, "description": "The `next` of the previous page.", "name": "after", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of people.", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "records": { "type": [ "integer", "null" ] }, "record_bytes": { "type": [ "integer", "null" ] }, "file_bytes": { "type": [ "integer", "null" ] } }, "required": [ "id", "first_seen_at", "last_seen_at", "records", "record_bytes", "file_bytes" ] } }, "next": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last." } }, "required": [ "people", "next" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/apps/{app}/users/{user}": { "get": { "operationId": "getPerson", "tags": [ "People" ], "summary": "Get one person's counts", "description": "Measured now, from their store.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "description": "The id the app's sign-in provider gives them, URL-encoded." }, "required": true, "description": "The id the app's sign-in provider gives them, URL-encoded.", "name": "user", "in": "path" } ], "responses": { "200": { "description": "The person.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "first_seen_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" }, "records": { "type": [ "integer", "null" ] }, "record_bytes": { "type": [ "integer", "null" ] }, "file_bytes": { "type": [ "integer", "null" ] } }, "required": [ "id", "first_seen_at", "last_seen_at", "records", "record_bytes", "file_bytes" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such app, or no such person in it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deletePerson", "tags": [ "People" ], "summary": "Delete a person's account in the app, for good", "description": "What `DELETE /v1/apps/{app}/me` does, on the person's behalf: their records, past versions and files, and their syncing from then on.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "description": "The id the app's sign-in provider gives them, URL-encoded." }, "required": true, "description": "The id the app's sign-in provider gives them, URL-encoded.", "name": "user", "in": "path" } ], "responses": { "200": { "description": "What was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "object", "properties": { "records": { "type": "integer" }, "files": { "type": "integer" } }, "required": [ "records", "files" ] } }, "required": [ "deleted" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such app, or no such person in it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/apps/{app}/export": { "get": { "operationId": "exportAppRecords", "tags": [ "Export" ], "summary": "Export every person's current records", "description": "Needs the owner or admin role, or a management key.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" } ], "responses": { "200": { "description": "One record per line, each with its `user_id`.", "content": { "application/x-ndjson": { "schema": { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": {} }, "user_id": { "type": "string" } }, "required": [ "collection", "id", "seq", "changed_at", "data", "user_id" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no app with this id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/apps/{app}/users/{user}/export": { "get": { "operationId": "exportPerson", "tags": [ "Export" ], "summary": "Export one person's current records", "description": "For a person's access request. Needs the owner or admin role, or a management key.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The app's id.", "example": "my-app" }, "required": true, "description": "The app's id.", "name": "app", "in": "path" }, { "schema": { "type": "string", "description": "The id the app's sign-in provider gives them, URL-encoded." }, "required": true, "description": "The id the app's sign-in provider gives them, URL-encoded.", "name": "user", "in": "path" } ], "responses": { "200": { "description": "One record per line.", "content": { "application/x-ndjson": { "schema": { "type": "object", "properties": { "collection": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "integer", "description": "This person's running change number." }, "changed_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "collection", "id", "seq", "changed_at", "data" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such app, or no such person in it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/organization": { "patch": { "operationId": "renameOrganization", "tags": [ "Your account" ], "summary": "Rename the account", "description": "An owner or admin of a hosted account.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/members": { "get": { "operationId": "listMembers", "tags": [ "Members" ], "summary": "List the account's members", "description": "An owner or admin of a hosted account.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "responses": { "200": { "description": "Every member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "joined_at": { "type": "string" } }, "required": [ "id", "name", "email", "role", "joined_at" ] } } }, "required": [ "members" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/members/{user}": { "patch": { "operationId": "updateMember", "tags": [ "Members" ], "summary": "Change a member's role", "description": "Owners and admins change roles; only an owner can make or unmake an owner, and the last owner stays.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The member's id." }, "required": true, "description": "The member's id.", "name": "user", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "The member now.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "joined_at": { "type": "string" } }, "required": [ "id", "name", "email", "role", "joined_at" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`last_owner`: the account must keep an owner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "removeMember", "tags": [ "Members" ], "summary": "Remove a member", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The member's id." }, "required": true, "description": "The member's id.", "name": "user", "in": "path" } ], "responses": { "204": { "description": "Removed." }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`last_owner`: the account must keep an owner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/invitations": { "get": { "operationId": "listInvitations", "tags": [ "Members" ], "summary": "List the account's invitations", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "responses": { "200": { "description": "Pending and expired invitations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "state": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "invited_by": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "created_at": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "email", "role", "state", "invited_by", "created_at", "expires_at" ] } } }, "required": [ "invitations" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createInvitation", "tags": [ "Members" ], "summary": "Invite someone by email", "description": "Emails them a link, valid for 7 days, that only that address can accept.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "default": "member" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "The invitation, sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "state": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "invited_by": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "created_at": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "email", "role", "state", "invited_by", "created_at", "expires_at" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invitation_pending`: a live invitation to that address is open; `already_a_member`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "`email_unavailable`: the invitation was made but its email could not be sent; resend it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/invitations/{invitation}/resend": { "post": { "operationId": "resendInvitation", "tags": [ "Members" ], "summary": "Send an invitation again, with a new link and deadline", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The invitation's id." }, "required": true, "description": "The invitation's id.", "name": "invitation", "in": "path" } ], "responses": { "200": { "description": "The invitation, sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "state": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "invited_by": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "created_at": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "email", "role", "state", "invited_by", "created_at", "expires_at" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`invitation_not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invitation_closed`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "503": { "description": "`email_unavailable`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/invitations/{invitation}/revoke": { "post": { "operationId": "revokeInvitation", "tags": [ "Members" ], "summary": "Revoke an invitation", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The invitation's id." }, "required": true, "description": "The invitation's id.", "name": "invitation", "in": "path" } ], "responses": { "200": { "description": "The invitation, revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "state": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "invited_by": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "created_at": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "email", "role", "state", "invited_by", "created_at", "expires_at" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`invitation_not_found`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invitation_closed`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/invitations/preview": { "post": { "operationId": "previewInvitation", "tags": [ "Members" ], "summary": "What an invitation link is for", "description": "Needs nobody signed in: holding the link's token is the authority. Hosted only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "From the invitation link's fragment." } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "The invitation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "state": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "invited_by": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "expires_at": { "type": "string" } }, "required": [ "id", "organization", "email", "role", "state", "invited_by", "expires_at" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "`rate_limited`: too many requests. Wait as many seconds as `Retry-After` says, then try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/invitations/mine": { "get": { "operationId": "listMyInvitations", "tags": [ "Members" ], "summary": "Invitations sent to the signed-in person's address", "description": "Only once that address is verified. Works for someone who belongs to no account yet.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "responses": { "200": { "description": "Their pending invitations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "state": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "invited_by": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "expires_at": { "type": "string" } }, "required": [ "id", "organization", "email", "role", "state", "invited_by", "expires_at" ] } } }, "required": [ "invitations" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/invitations/accept": { "post": { "operationId": "acceptInvitation", "tags": [ "Members" ], "summary": "Accept an invitation and join the account", "description": "By the link's token, or by id once the address is verified. Works for someone who belongs to no account yet.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "From the invitation link's fragment." } }, "required": [ "token" ] }, { "type": "object", "properties": { "invitation_id": { "type": "string", "minLength": 1 } }, "required": [ "invitation_id" ] } ] } } } }, "responses": { "200": { "description": "The caller, now acting on that account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "cloudflare_access", "hosted" ], "description": "How this deployment signs people in." }, "via": { "type": "string", "enum": [ "session", "access", "key" ], "description": "How this caller signed in: the hosted console, Cloudflare Access, or a management key." }, "user": { "type": [ "object", "null" ], "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" } }, "required": [ "email", "name", "email_verified" ], "description": "The person, for a hosted sign-in; null for Cloudflare Access and keys." }, "email": { "type": [ "string", "null" ], "description": "Who signed in, where known." }, "organization": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "description": "The account this request acts on; null for someone invited who has not accepted yet." }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", null ] }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "id", "name", "role" ] }, "description": "Every account the person belongs to; only the current one for keys and Cloudflare Access." } }, "required": [ "mode", "via", "user", "email", "organization", "role", "organizations" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/invitations/decline": { "post": { "operationId": "declineInvitation", "tags": [ "Members" ], "summary": "Decline an invitation", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "From the invitation link's fragment." } }, "required": [ "token" ] }, { "type": "object", "properties": { "invitation_id": { "type": "string", "minLength": 1 } }, "required": [ "invitation_id" ] } ] } } } }, "responses": { "200": { "description": "The invitation, declined.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "state": { "type": "string", "enum": [ "pending", "accepted", "declined", "revoked", "expired" ] }, "invited_by": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "expires_at": { "type": "string" } }, "required": [ "id", "organization", "email", "role", "state", "invited_by", "expires_at" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`. `forbidden` also when the deployment is behind Cloudflare Access, which decides who manages it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "`invitation_not_found`, `invitation_expired` (410), `invitation_closed`, `invitation_email_mismatch` (signed in as another address), `email_unverified`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/cli/login": { "post": { "operationId": "openCliLogin", "tags": [ "CLI" ], "summary": "Ask to log a CLI in, approved in the console", "description": "The CLI makes 32 random bytes as its `token` and keeps them; only their digest is stored. A person who may make keys approves the link in the hosted console, and the CLI collects a management key with `poll`. Hosted only: behind Cloudflare Access, log in with a key made in the console.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 128 }, "label": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Names the key, such as `CLI on mac-studio`." } }, "required": [ "token", "label" ] } } } }, "responses": { "200": { "description": "The request, pending.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "user_code": { "type": "string", "description": "Shown in the terminal; the approval page shows it too, to compare." }, "approval_url": { "type": "string", "description": "Open it in a browser signed in to the console; the proof is in its fragment." }, "expires_at": { "type": "string" } }, "required": [ "id", "user_code", "approval_url", "expires_at" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`route_not_found`: this deployment is behind Cloudflare Access.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`conflict`: the token was used for another request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "`rate_limited`: too many requests. Wait as many seconds as `Retry-After` says, then try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/cli/login/poll": { "post": { "operationId": "pollCliLogin", "tags": [ "CLI" ], "summary": "Where a CLI login stands, and its key once approved", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "id", "token" ] } } } }, "responses": { "200": { "description": "The request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "pending", "completed", "denied", "expired", "retired" ] }, "key": { "type": "string", "description": "The management key, once approved: handed over once, for about 15 minutes." }, "organization_id": { "type": [ "string", "null" ] } }, "required": [ "state" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such request for this token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "410": { "description": "`operation_expired`: the key was revoked before it was collected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/cli/login/deny": { "post": { "operationId": "denyCliLogin", "tags": [ "CLI" ], "summary": "Refuse a CLI login", "description": "Needs nobody signed in: someone sent a link they did not ask for can always refuse it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "proof": { "type": "string", "minLength": 1 } }, "required": [ "id", "proof" ] } } } }, "responses": { "200": { "description": "Refused.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "denied" ] } }, "required": [ "state" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "`rate_limited`: too many requests. Wait as many seconds as `Retry-After` says, then try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/cli/login": { "post": { "operationId": "getCliLogin", "tags": [ "CLI" ], "summary": "What a CLI login asks, for the approval page", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "proof": { "type": "string", "minLength": 1 } }, "required": [ "id", "proof" ] } } } }, "responses": { "200": { "description": "The request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "completed", "denied", "expired", "retired" ] }, "label": { "type": [ "string", "null" ], "description": "What the CLI called itself, such as `CLI on mac-studio`." }, "user_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "blocked_by": { "type": [ "string", "null" ], "description": "Why this person cannot approve it here, if they cannot." } }, "required": [ "id", "state", "label", "user_code", "created_at", "expires_at", "blocked_by" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/v1/admin/cli/login/approve": { "post": { "operationId": "approveCliLogin", "tags": [ "CLI" ], "summary": "Approve a CLI login into the current account", "description": "An owner or admin signed in to the hosted console. Makes a management key named after the CLI's label.", "security": [ { "ManagementKey": [] }, { "ConsoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "proof": { "type": "string", "minLength": 1 } }, "required": [ "id", "proof" ] } } } }, "responses": { "200": { "description": "Approved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "completed" ] } }, "required": [ "state" ] } } } }, "400": { "description": "`validation_error`: the request does not match this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "`auth_required`: not signed in, and no management key, or one that was revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "`forbidden`: the caller's role does not allow this, a management key asked for what only a person may do, or a cookie-signed request did not come from the console. `email_unverified`: confirm the email address first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "`not_found`: no such request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "`conflict`: already answered, or the approver's access changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable: what the client acts on." }, "message": { "type": "string", "description": "Safe to show; may change." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {} }