@1claw/openapi-spec 0.20.0 → 0.21.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.10.0",
+    "version": "2.11.0",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -267,7 +267,7 @@
           "Authentication"
         ],
         "summary": "Get JWT verification public key",
-        "description": "Returns the Ed25519 public key used to sign JWTs.\nUse this to verify tokens independently (e.g. in a TEE proxy or\ngateway). No authentication required.\n",
+        "description": "Returns the Ed25519 public key used to sign JWTs.\nUse this to verify tokens independently (e.g. in a TEE proxy or\ngateway). No authentication required.\n\nFor OIDC-compliant relying parties (Anthropic Workload Identity\nFederation, etc.) prefer the JWKS endpoint at\n`/.well-known/jwks.json` together with the discovery document\nat `/.well-known/openid-configuration` — those advertise both\nEd25519 and RS256 keys keyed by `kid` and survive key rotation.\n",
         "operationId": "getJwtPublicKey",
         "security": [],
         "responses": {
@@ -298,6 +298,110 @@
         }
       }
     },
+    "/v1/auth/federated-token": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Exchange a 1claw token for an OIDC federation token (RFC 8693)",
+        "description": "Mints a short-lived RS256-signed JWT targeted at an external\nrelying party (e.g. Anthropic Workload Identity Federation).\nThe relying party validates the token via this issuer's JWKS\nURL (`/.well-known/jwks.json`) and exchanges it for its own\nshort-lived service credentials.\n\nRequirements:\n- The agent that owns the `subject_token` must have\n  `federation_enabled = true` and the requested `audience`\n  must appear in `federation_audiences`.\n- The `subject_token` must be a valid 1claw agent JWT or\n  `ocv_` API key.\n- Optional `scope` narrows the agent's existing scopes — it\n  cannot escalate.\n\nReturns 503 when `ONECLAW_JWT_RS256_SIGNING_KEY_ID` is not\nconfigured on the server.\n",
+        "operationId": "exchangeFederatedToken",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TokenExchangeRequest"
+              }
+            },
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "$ref": "#/components/schemas/TokenExchangeRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Federation token issued",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TokenExchangeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "503": {
+            "description": "RS256 signing key not configured"
+          }
+        }
+      }
+    },
+    "/.well-known/openid-configuration": {
+      "get": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "OIDC discovery document",
+        "description": "Standard OpenID Connect discovery document advertising the\nissuer URL, JWKS URL, supported algorithms (`EdDSA`, `RS256`),\nand the RFC 8693 token-exchange endpoint. External IdPs\n(Anthropic WIF, Okta, Auth0, etc.) read this URL to learn\nwhere 1claw publishes its JWKS.\n",
+        "operationId": "openidConfiguration",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Discovery document",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/.well-known/jwks.json": {
+      "get": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "JSON Web Key Set",
+        "description": "Public keys for every active version of every JWT signing\nkey (Ed25519 + RSA-2048). Each entry includes a `kid` so\nconsumers can validate tokens issued before the most recent\nkey rotation. Cached for 5 minutes via `Cache-Control` and\nCORS-permissive for browser-based IdP consoles.\n",
+        "operationId": "jwks",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "JWK Set",
+            "content": {
+              "application/jwk-set+json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "keys": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/auth/signup": {
       "post": {
         "tags": [
@@ -1708,7 +1812,7 @@
         }
       }
     },
-    "/v1/vaults/{vault_id}/secret-version/{path}/{version}/disable": {
+    "/v1/vaults/{vault_id}/secret-version-disable/{path}/{version}": {
       "post": {
         "tags": [
           "Secrets"
@@ -1922,7 +2026,7 @@
         ],
         "summary": "Self-enroll an agent",
         "operationId": "enrollAgent",
-        "description": "Public endpoint (no auth required). Creates an agent under the human's org\nand emails the credentials to the specified human email. The API key is NOT\nreturned in the response. Anti-spam: IP rate limiting + per-email cooldown.\n",
+        "description": "Public endpoint (no auth required).\n\n**With `human_email`:** Creates a pending enrollment for that account's org,\nemails Allow/Deny links, and returns `approval_url` in the JSON body (use if email\nis delayed). The API key is NOT returned until the human approves.\n\n**Name only (omit `human_email`):** Creates a link-only pending enrollment.\nThe response includes `approval_url`; the human opens it while signed in to\napprove the agent into their org.\n\nAnti-spam: IP rate limiting, per-email cooldown, caps on pending rows.\n",
         "requestBody": {
           "required": true,
           "content": {
@@ -2542,6 +2646,181 @@
         }
       }
     },
+    "/v1/agents/{agent_id}/signing-keys": {
+      "post": {
+        "tags": [
+          "Signing Keys"
+        ],
+        "summary": "Provision a signing key for a chain",
+        "operationId": "createSigningKey",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateSigningKeyRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Signing key created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SigningKeyResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Signing Keys"
+        ],
+        "summary": "List signing keys for an agent",
+        "operationId": "listSigningKeys",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Signing keys list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SigningKeyListResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/signing-keys/{chain}/rotate": {
+      "post": {
+        "tags": [
+          "Signing Keys"
+        ],
+        "summary": "Rotate a signing key for a chain",
+        "operationId": "rotateSigningKey",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Rotated signing key",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SigningKeyResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/signing-keys/{chain}": {
+      "delete": {
+        "tags": [
+          "Signing Keys"
+        ],
+        "summary": "Deactivate a signing key for a chain",
+        "operationId": "deactivateSigningKey",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "chain",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Key deactivated"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/sign": {
+      "post": {
+        "tags": [
+          "Signing"
+        ],
+        "summary": "Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)",
+        "operationId": "signIntent",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SignIntentRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Signed result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SignIntentResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
     "/v1/chains": {
       "get": {
         "tags": [
@@ -4704,6 +4983,16 @@
             }
           }
         }
+      },
+      "Conflict": {
+        "description": "Resource already exists or conflict",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
       }
     },
     "schemas": {
@@ -4868,6 +5157,76 @@
           }
         }
       },
+      "TokenExchangeRequest": {
+        "type": "object",
+        "required": [
+          "grant_type",
+          "subject_token",
+          "subject_token_type",
+          "audience"
+        ],
+        "description": "RFC 8693 token-exchange request body. `subject_token_type`\naccepts the standard JWT URI or 1claw's API-key URI:\n  - `urn:ietf:params:oauth:token-type:jwt`\n  - `urn:1claw:params:oauth:token-type:api-key`\n",
+        "properties": {
+          "grant_type": {
+            "type": "string",
+            "enum": [
+              "urn:ietf:params:oauth:grant-type:token-exchange"
+            ]
+          },
+          "subject_token": {
+            "type": "string",
+            "description": "1claw JWT or `ocv_` API key authorising the exchange."
+          },
+          "subject_token_type": {
+            "type": "string",
+            "enum": [
+              "urn:ietf:params:oauth:token-type:jwt",
+              "urn:1claw:params:oauth:token-type:api-key"
+            ]
+          },
+          "audience": {
+            "type": "string",
+            "format": "uri",
+            "description": "Required `aud` claim for the issued federation token (must be in agent's allowlist).",
+            "example": "https://api.anthropic.com"
+          },
+          "scope": {
+            "type": "string",
+            "description": "Optional space-separated subset of the agent's existing scopes."
+          },
+          "requested_token_type": {
+            "type": "string",
+            "description": "Optional. Defaults to `urn:ietf:params:oauth:token-type:jwt`."
+          }
+        }
+      },
+      "TokenExchangeResponse": {
+        "type": "object",
+        "required": [
+          "access_token",
+          "issued_token_type",
+          "token_type",
+          "expires_in"
+        ],
+        "properties": {
+          "access_token": {
+            "type": "string",
+            "description": "RS256-signed federation JWT."
+          },
+          "issued_token_type": {
+            "type": "string"
+          },
+          "token_type": {
+            "type": "string"
+          },
+          "expires_in": {
+            "type": "integer"
+          },
+          "scope": {
+            "type": "string"
+          }
+        }
+      },
       "SignupRequest": {
         "type": "object",
         "required": [
@@ -5766,8 +6125,7 @@
       "EnrollAgentRequest": {
         "type": "object",
         "required": [
-          "name",
-          "human_email"
+          "name"
         ],
         "properties": {
           "name": {
@@ -5777,7 +6135,7 @@
           "human_email": {
             "type": "string",
             "format": "email",
-            "description": "Email of the human who will receive the agent credentials"
+            "description": "Optional. If set, pending enrollment is bound to that 1Claw account email\nand Allow/Deny links are emailed. If omitted, only `approval_url` is used\n(link-only enrollment; human must open the URL while signed in).\n"
           },
           "description": {
             "type": "string",
@@ -5791,11 +6149,16 @@
           "agent_id": {
             "type": "string",
             "format": "uuid",
-            "description": "UUID of the created agent (nil UUID when email not found — uniform response)"
+            "description": "UUID of the created agent (nil UUID until approved — uniform response)"
           },
           "message": {
             "type": "string",
-            "description": "Status message (always generic to prevent email enumeration)"
+            "description": "Status message (worded to limit email enumeration where applicable)"
+          },
+          "approval_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Present when a pending enrollment was created and the client should show\nthis link (email flow includes it as a fallback; name-only flow requires it).\n"
           }
         }
       },
@@ -5945,6 +6308,25 @@
           },
           "shroud_config": {
             "$ref": "#/components/schemas/ShroudConfig"
+          },
+          "federation_enabled": {
+            "type": "boolean",
+            "description": "Enable OIDC federation (RFC 8693 token-exchange) for this agent.\nWhen true, the agent may call POST /v1/auth/federated-token to mint\nfederation tokens for the audiences listed in `federation_audiences`.\n"
+          },
+          "federation_audiences": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            },
+            "description": "Allowlist of `aud` values the federation token-exchange may issue\ntokens for (e.g. `[\"https://api.anthropic.com\"]`). Empty array\nblocks all federation requests (zero-trust default).\n"
+          },
+          "federated_token_ttl_seconds": {
+            "type": "integer",
+            "minimum": 60,
+            "maximum": 3600,
+            "nullable": true,
+            "description": "Per-agent TTL override for federation tokens (seconds). NULL falls\nback to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).\nHard-capped at 3600 seconds.\n"
           }
         }
       },
@@ -6050,6 +6432,49 @@
           "shroud_config": {
             "$ref": "#/components/schemas/ShroudConfig"
           },
+          "federation_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent may mint OIDC federation tokens via\nPOST /v1/auth/federated-token. False by default.\n"
+          },
+          "federation_audiences": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            },
+            "description": "Allowlist of audience URIs the agent may federate to."
+          },
+          "federated_token_ttl_seconds": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Per-agent TTL override for federation tokens (60..=3600)."
+          },
+          "signing_chains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Chains for which this agent has provisioned signing keys."
+          },
+          "eip712_domain_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "JSON array of allowed EIP-712 domain entries."
+          },
+          "eip712_default_policy": {
+            "type": "string",
+            "enum": [
+              "deny",
+              "allow"
+            ],
+            "description": "Default EIP-712 policy (deny blocks all unless allowlisted)."
+          },
+          "message_signing_enabled": {
+            "type": "boolean",
+            "description": "Whether EIP-191 personal_sign is enabled."
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"
@@ -6967,6 +7392,195 @@
           }
         }
       },
+      "CreateSigningKeyRequest": {
+        "type": "object",
+        "required": [
+          "chain"
+        ],
+        "properties": {
+          "chain": {
+            "type": "string",
+            "enum": [
+              "ethereum",
+              "bitcoin",
+              "solana",
+              "xrp",
+              "cardano",
+              "tron"
+            ]
+          }
+        }
+      },
+      "SigningKeyResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "chain": {
+            "type": "string"
+          },
+          "curve": {
+            "type": "string"
+          },
+          "public_key": {
+            "type": "string"
+          },
+          "address": {
+            "type": "string",
+            "nullable": true
+          },
+          "key_version": {
+            "type": "integer"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "rotated_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          }
+        }
+      },
+      "SigningKeyListResponse": {
+        "type": "object",
+        "properties": {
+          "keys": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SigningKeyResponse"
+            }
+          }
+        }
+      },
+      "SignIntentRequest": {
+        "type": "object",
+        "required": [
+          "intent_type",
+          "chain"
+        ],
+        "properties": {
+          "intent_type": {
+            "type": "string",
+            "enum": [
+              "personal_sign",
+              "typed_data",
+              "transaction"
+            ]
+          },
+          "chain": {
+            "type": "string"
+          },
+          "signing_key_path": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string",
+            "description": "Hex-encoded message bytes (for personal_sign)"
+          },
+          "typed_data": {
+            "type": "object",
+            "description": "EIP-712 typed data JSON (for typed_data)"
+          },
+          "tx_type": {
+            "type": "integer",
+            "description": "EIP-2718 type: 0=legacy, 1=2930, 2=1559, 3=4844, 4=7702"
+          },
+          "to": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          },
+          "data": {
+            "type": "string"
+          },
+          "nonce": {
+            "type": "integer"
+          },
+          "gas_limit": {
+            "type": "integer"
+          },
+          "gas_price": {
+            "type": "string"
+          },
+          "max_fee_per_gas": {
+            "type": "string"
+          },
+          "max_priority_fee_per_gas": {
+            "type": "string"
+          },
+          "access_list": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            }
+          },
+          "max_fee_per_blob_gas": {
+            "type": "string"
+          },
+          "blob_versioned_hashes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "authorization_list": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            }
+          }
+        }
+      },
+      "SignIntentResponse": {
+        "type": "object",
+        "properties": {
+          "intent_type": {
+            "type": "string"
+          },
+          "chain": {
+            "type": "string"
+          },
+          "from": {
+            "type": "string"
+          },
+          "signature": {
+            "type": "string",
+            "nullable": true
+          },
+          "signed_tx": {
+            "type": "string",
+            "nullable": true
+          },
+          "tx_hash": {
+            "type": "string",
+            "nullable": true
+          },
+          "message_hash": {
+            "type": "string",
+            "nullable": true
+          },
+          "typed_data_hash": {
+            "type": "string",
+            "nullable": true
+          },
+          "tx_type": {
+            "type": "integer",
+            "nullable": true
+          }
+        }
+      },
       "TransactionResponse": {
         "type": "object",
         "properties": {
@@ -8446,6 +9060,36 @@
               "type": "string"
             }
           },
+          "response_injection_score": {
+            "type": "number",
+            "description": "Response-side prompt-injection score (0.0–1.0)."
+          },
+          "response_context_injection_score": {
+            "type": "number",
+            "description": "Response-side context-injection score (0.0–1.0)."
+          },
+          "response_injection_categories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Category tags emitted by the response-side filters (e.g. `markdown_image_exfil`, `data_uri_blob`, `echoed_instruction`)."
+          },
+          "external_urls_flagged": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "URLs emitted by the model that were flagged as potential exfil / callback targets."
+          },
+          "unexpected_code_blocks": {
+            "type": "integer",
+            "description": "Number of code fences in the response that were not expected for the agent's allowed task set."
+          },
+          "content_filtered": {
+            "type": "boolean",
+            "description": "True when Shroud rewrote or blocked response content before returning it to the agent."
+          },
           "metadata": {
             "type": "object"
           },
@@ -8505,6 +9149,34 @@
           },
           "metadata": {
             "type": "object"
+          },
+          "response_injection_score": {
+            "type": "number",
+            "default": 0
+          },
+          "response_context_injection_score": {
+            "type": "number",
+            "default": 0
+          },
+          "response_injection_categories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "external_urls_flagged": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "unexpected_code_blocks": {
+            "type": "integer",
+            "default": 0
+          },
+          "content_filtered": {
+            "type": "boolean",
+            "default": false
           }
         }
       },