{ "openapi": "3.1.0", "info": { "title": "PhysicsBase API", "version": "0.2.0", "description": "Identity for AI agents with no humans in the loop. Agents register themselves with their own Ed25519 key, get short-lived DPoP-bound tokens per app, and call other APIs through the organisation's credential vault." }, "servers": [ { "url": "/" } ], "tags": [ { "name": "Agents" }, { "name": "OAuth" }, { "name": "Discovery" }, { "name": "Hosted" }, { "name": "Management", "description": "Manage an organisation from code with an API token" } ], "paths": { "/agent/register": { "post": { "tags": [ "Agents" ], "summary": "Register an agent with no human involved", "description": "The assertion is signed by the agent's own key, carries that public key in its `jwk` header and uses `typ: physicsbase-register+jwt`. Payload: `aud` (issuer), `iat`, `exp` (\u2264120 s), `jti`, `name`, optional `enrollment_key`. Without an enrollment key the agent is independent and acts as itself.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assertion" ], "properties": { "assertion": { "type": "string", "description": "Compact JWS (EdDSA)" } } } } } }, "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string" }, "issuer": { "type": "string" }, "fingerprint": { "type": "string" }, "acting_for": { "type": "string", "description": "'self', 'owner' or the owner's email" }, "expires_at": { "type": [ "integer", "null" ] } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/token": { "post": { "tags": [ "Agents" ], "summary": "Get a key-bound token for one app", "description": "Assertion `typ: physicsbase-agent+jwt`, signed by the agent key, with `iss`=`sub`=agent ID, `aud`=issuer, `jti`, `exp` \u2264120 s, `resource` (app client ID or URL), optional `scope`, `reason`, `approval_id`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assertion" ], "properties": { "assertion": { "type": "string", "description": "Compact JWS (EdDSA)" } } } } } }, "responses": { "200": { "description": "Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Refused by policy, or `approval_required` when a checkpoint is configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited or daily_limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/whoami": { "post": { "tags": [ "Agents" ], "summary": "Read the agent's own policy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assertion": { "type": "string", "description": "Compact JWS (EdDSA)" } } } } } }, "responses": { "200": { "description": "Identity and mandate" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/approvals/{id}": { "get": { "tags": [ "Agents" ], "summary": "Poll an optional person checkpoint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "pending", "approved", "denied", "used", "expired" ] } } } } } } } } }, "/agent/link": { "post": { "tags": [ "Agents" ], "summary": "Optional: ask one person to approve this agent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "jwk": { "type": "object" } } } } } }, "responses": { "201": { "description": "Code and link for the person" } } } }, "/token": { "post": { "tags": [ "OAuth" ], "summary": "OAuth token endpoint", "description": "`authorization_code` (+PKCE) for people signing in to apps. `urn:ietf:params:oauth:grant-type:jwt-bearer` (RFC 7523) with a `DPoP` header (RFC 9449) for agents: send `assertion`, `resource` and optional `scope`; the DPoP key must be the agent's key.", "parameters": [ { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string", "description": "Compact JWS (EdDSA)" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string" }, "assertion": { "type": "string", "description": "Compact JWS (EdDSA)" }, "resource": { "type": "string" }, "scope": { "type": "string" }, "code": { "type": "string" }, "code_verifier": { "type": "string" }, "client_id": { "type": "string" }, "redirect_uri": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "Discovery" ], "summary": "Authorization server metadata (RFC 8414)", "responses": { "200": { "description": "Metadata" } } } }, "/.well-known/openid-configuration": { "get": { "tags": [ "Discovery" ], "summary": "OpenID-style discovery", "responses": { "200": { "description": "Metadata" } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "Discovery" ], "summary": "Public keys that sign PhysicsBase tokens", "responses": { "200": { "description": "JWK set" } } } }, "/agent/broker": { "post": { "tags": [ "Agents" ], "summary": "Call a third-party API through the credential vault", "description": "PhysicsBase checks the agent's policy and limits, injects the stored credential for the URL's host, adds Web Bot Auth signature headers and makes the request. The agent never sees the credential. Only agents enrolled in an organisation may use it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assertion", "url" ], "properties": { "assertion": { "type": "string", "description": "Compact JWS (EdDSA), typ physicsbase-agent+jwt" }, "method": { "type": "string", "default": "GET" }, "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "string", "nullable": true, "description": "Request body, base64" }, "reason": { "type": "string", "maxLength": 200, "description": "Why the agent is making this call. Stored in the activity log." } } } } } }, "responses": { "200": { "description": "The API's response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "string", "description": "Response body, base64" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "no_vault, no_connection, connection_not_allowed, revoked, blocked_target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited or daily_limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/http-message-signatures-directory": { "get": { "tags": [ "Discovery" ], "summary": "Web Bot Auth key directory", "responses": { "200": { "description": "JWKS of keys that sign brokered requests", "content": { "application/http-message-signatures-directory+json": { "schema": { "type": "object" } } } } } } }, "/proxy/{url}": { "parameters": [ { "name": "url", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Absolute target URL, e.g. https://api.stripe.com/v1/charges" }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer pbk_\u2026 (an enrollment key)" }, { "name": "X-PhysicsBase-Agent", "in": "header", "schema": { "type": "string" }, "description": "Agent name; one identity per name" }, { "name": "X-PhysicsBase-Reason", "in": "header", "schema": { "type": "string" } }, { "name": "X-PhysicsBase-Scope", "in": "header", "schema": { "type": "string" } } ], "get": { "tags": [ "Hosted" ], "summary": "GET a URL as a hosted agent", "description": "PhysicsBase apps get the agent's key-bound token; other APIs go through the vault. The response is the target's response.", "responses": { "default": { "description": "The target's response" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Hosted" ], "summary": "POST a URL as a hosted agent", "description": "PhysicsBase apps get the agent's key-bound token; other APIs go through the vault. The response is the target's response.", "responses": { "default": { "description": "The target's response" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Hosted" ], "summary": "PUT a URL as a hosted agent", "description": "PhysicsBase apps get the agent's key-bound token; other APIs go through the vault. The response is the target's response.", "responses": { "default": { "description": "The target's response" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Hosted" ], "summary": "PATCH a URL as a hosted agent", "description": "PhysicsBase apps get the agent's key-bound token; other APIs go through the vault. The response is the target's response.", "responses": { "default": { "description": "The target's response" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Hosted" ], "summary": "DELETE a URL as a hosted agent", "description": "PhysicsBase apps get the agent's key-bound token; other APIs go through the vault. The response is the target's response.", "responses": { "default": { "description": "The target's response" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "tags": [ "Hosted" ], "summary": "Hosted MCP server (Streamable HTTP, JSON responses)", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer pbk_\u2026 (an enrollment key)" }, { "name": "X-PhysicsBase-Agent", "in": "header", "schema": { "type": "string" }, "description": "Agent name; one identity per name" }, { "name": "X-PhysicsBase-Reason", "in": "header", "schema": { "type": "string" } }, { "name": "X-PhysicsBase-Scope", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 message or batch" } } } }, "responses": { "200": { "description": "JSON-RPC response" }, "202": { "description": "Notification accepted" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/token": { "get": { "tags": [ "Management" ], "summary": "The token, its role and organisation", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agents": { "get": { "tags": [ "Management" ], "summary": "List agents", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/agents/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "tags": [ "Management" ], "summary": "Change an agent's policy", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "tags": [ "Management" ], "summary": "Revoke an agent", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/enrollment-keys": { "get": { "tags": [ "Management" ], "summary": "List enrollment keys", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Management" ], "summary": "Create an enrollment key (secret returned once)", "security": [ { "apiToken": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/enrollment-keys/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Management" ], "summary": "Revoke a key and its agents", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/connections": { "get": { "tags": [ "Management" ], "summary": "List vault connections", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Management" ], "summary": "Add a vault connection", "security": [ { "apiToken": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/connections/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Management" ], "summary": "Remove a vault connection", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/connections/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Management" ], "summary": "Rotate a connection secret", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/activity": { "get": { "tags": [ "Management" ], "summary": "Search the activity log", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/usage": { "get": { "tags": [ "Management" ], "summary": "Usage this month", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/alerts": { "get": { "tags": [ "Management" ], "summary": "Alert settings", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Management" ], "summary": "Change alert settings", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/approvals": { "get": { "tags": [ "Management" ], "summary": "Checkpoints waiting for a person", "security": [ { "apiToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Token": { "type": "object", "properties": { "access_token": { "type": "string", "description": "EdDSA JWT, typ at+jwt. Claims: iss, aud (client ID), sub (pairwise), sub_type ('agent'|'person'), act {sub,name}, scope, cnf.jkt, exp, jti, once?" }, "token_type": { "const": "DPoP" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" }, "single_use": { "type": "boolean" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } }, "securitySchemes": { "apiToken": { "type": "http", "scheme": "bearer", "description": "Management API token (pbm_\u2026) from Dashboard \u2192 API tokens" } } } }