@1claw/openapi-spec 0.23.1 → 0.24.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.12.0",
+    "version": "2.14.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"
@@ -99,6 +99,10 @@
       "name": "Health",
       "description": "Service health checks"
     },
+    {
+      "name": "Approvals",
+      "description": "Human-in-the-loop approval workflow for agent actions"
+    },
     {
       "name": "Platform",
       "description": "Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)"
@@ -1263,6 +1267,230 @@
         }
       }
     },
+    "/v1/auth/devices": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Register a mobile device",
+        "description": "Register a new mobile device for the authenticated user. Human-only.\nThe device public key is used for step-up authentication challenges.\n",
+        "operationId": "registerDevice",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RegisterDeviceRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Device registered",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RegisterDeviceResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "List devices for current user",
+        "description": "Returns all registered mobile devices for the authenticated user.",
+        "operationId": "listDevices",
+        "responses": {
+          "200": {
+            "description": "Device list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceListResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/auth/devices/{device_id}": {
+      "delete": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Revoke a device",
+        "description": "Removes a registered device, invalidating its keys and push tokens.",
+        "operationId": "revokeDevice",
+        "parameters": [
+          {
+            "name": "device_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Device revoked"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/auth/devices/{device_id}/challenge": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Create step-up auth challenge",
+        "description": "Creates a cryptographic challenge bound to a specific action (e.g. approving\na high-risk transaction). The device signs the challenge nonce to prove\npossession of the private key.\n",
+        "operationId": "createDeviceChallenge",
+        "parameters": [
+          {
+            "name": "device_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateDeviceChallengeRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Challenge created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeviceChallengeResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/auth/devices/{device_id}/attest": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Attest device challenge",
+        "description": "Submit a signed challenge nonce to complete step-up authentication.\nReturns a short-lived step-up token that can be used for the bound action.\n",
+        "operationId": "attestDeviceChallenge",
+        "parameters": [
+          {
+            "name": "device_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AttestDeviceChallengeRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Attestation successful",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AttestDeviceChallengeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/auth/devices/{device_id}/push-token": {
+      "post": {
+        "tags": [
+          "Authentication"
+        ],
+        "summary": "Register push notification token",
+        "description": "Associates a push notification token (APNs or FCM) with a registered device\nso the server can send approval requests and alerts.\n",
+        "operationId": "registerPushToken",
+        "parameters": [
+          {
+            "name": "device_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RegisterPushTokenRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "Push token registered"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/vaults": {
       "post": {
         "tags": [
@@ -5749,56 +5977,286 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "BearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      },
-      "ApiKeyAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "1ck_ prefixed API key used as Bearer token"
-      }
     },
-    "parameters": {
-      "VaultId": {
-        "name": "vault_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "SecretPath": {
-        "name": "path",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string"
-        },
-        "description": "Secret path (e.g. \"db/credentials\")"
-      },
-      "AgentId": {
-        "name": "agent_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
+    "/v1/platform/claim/{token}": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Preview a claim token",
+        "description": "Verify a claim token and preview what was provisioned (app name, vaults, agents, policies).\nPublic endpoint — the token itself is the authentication.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "token",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The `ct_` prefixed claim token from the bootstrap response"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Claim preview",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClaimPreviewResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Invalid or expired claim token"
+          }
         }
       },
-      "PolicyId": {
-        "name": "policy_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Redeem a claim token",
+        "description": "Redeem a one-time claim token, marking the connection as claimed.\nPublic endpoint — the token itself is the authentication. Returns 409 if already claimed, 410 if expired.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "token",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The `ct_` prefixed claim token from the bootstrap response"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Claim redeemed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ClaimRedeemResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Invalid claim token"
+          },
+          "409": {
+            "description": "Claim token already used"
+          },
+          "410": {
+            "description": "Claim token has expired"
+          }
+        }
+      }
+    },
+    "/v1/approvals": {
+      "get": {
+        "tags": [
+          "Approvals"
+        ],
+        "summary": "List pending approvals",
+        "description": "Returns approvals for the authenticated user's organization.\nHuman-only. Supports filtering by status and pagination.\n",
+        "operationId": "listApprovals",
+        "parameters": [
+          {
+            "name": "status",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "pending",
+                "approved",
+                "rejected",
+                "expired"
+              ]
+            },
+            "description": "Filter by approval status"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 50
+            }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 0
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Approval list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "approvals"
+                  ],
+                  "properties": {
+                    "approvals": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/ApprovalResponse"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/approvals/{approval_id}": {
+      "get": {
+        "tags": [
+          "Approvals"
+        ],
+        "summary": "Get approval details",
+        "description": "Returns details for a single approval by ID.",
+        "operationId": "getApproval",
+        "parameters": [
+          {
+            "name": "approval_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Approval details",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApprovalResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/approvals/{approval_id}/decide": {
+      "post": {
+        "tags": [
+          "Approvals"
+        ],
+        "summary": "Approve or reject",
+        "description": "Submit a decision (approve or reject) for a pending approval.\nHuman-only. The approval must be in `pending` status.\n",
+        "operationId": "decideApproval",
+        "parameters": [
+          {
+            "name": "approval_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DecideApprovalRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Decision recorded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApprovalResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      },
+      "ApiKeyAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "1ck_ prefixed API key used as Bearer token"
+      }
+    },
+    "parameters": {
+      "VaultId": {
+        "name": "vault_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "SecretPath": {
+        "name": "path",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        },
+        "description": "Secret path (e.g. \"db/credentials\")"
+      },
+      "AgentId": {
+        "name": "agent_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "PolicyId": {
+        "name": "policy_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
         }
       },
       "IncludeSignedTx": {
@@ -10660,6 +11118,39 @@
                   "type": "string",
                   "format": "uuid"
                 }
+              },
+              "signing_key_chains": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Chains with provisioned signing keys"
+              },
+              "agent_api_key": {
+                "type": "string",
+                "nullable": true,
+                "description": "One-time agent API key (ocv_ prefix). Store securely — not retrievable later."
+              },
+              "signing_keys": {
+                "type": "array",
+                "description": "Provisioned signing key details (chain, address, public key)",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "chain": {
+                      "type": "string"
+                    },
+                    "curve": {
+                      "type": "string"
+                    },
+                    "public_key": {
+                      "type": "string"
+                    },
+                    "address": {
+                      "type": "string"
+                    }
+                  }
+                }
               }
             }
           }
@@ -10700,6 +11191,379 @@
             "format": "date-time"
           }
         }
+      },
+      "ClaimPreviewResponse": {
+        "type": "object",
+        "properties": {
+          "app_name": {
+            "type": "string"
+          },
+          "app_slug": {
+            "type": "string"
+          },
+          "app_logo_url": {
+            "type": "string",
+            "nullable": true
+          },
+          "auth_mode": {
+            "type": "string"
+          },
+          "vault_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          "agent_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          "policy_count": {
+            "type": "integer"
+          },
+          "status": {
+            "type": "string"
+          },
+          "already_claimed": {
+            "type": "boolean"
+          },
+          "expired": {
+            "type": "boolean"
+          },
+          "return_to": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "ClaimRedeemResponse": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string"
+          },
+          "connection_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "vault_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          "agent_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          "return_to": {
+            "type": "string",
+            "nullable": true
+          },
+          "dashboard_url": {
+            "type": "string"
+          }
+        }
+      },
+      "RegisterDeviceRequest": {
+        "type": "object",
+        "required": [
+          "name",
+          "platform",
+          "public_key_pem"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable device name (e.g. \"Kevin's iPhone\")",
+            "example": "My iPhone"
+          },
+          "platform": {
+            "type": "string",
+            "enum": [
+              "ios",
+              "android"
+            ]
+          },
+          "public_key_pem": {
+            "type": "string",
+            "description": "PEM-encoded public key for step-up challenge signing"
+          },
+          "attestation_blob": {
+            "type": "string",
+            "description": "Optional platform attestation (Apple DeviceCheck / Android SafetyNet)"
+          }
+        }
+      },
+      "RegisterDeviceResponse": {
+        "type": "object",
+        "required": [
+          "device_id",
+          "attestation_verified"
+        ],
+        "properties": {
+          "device_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "attestation_verified": {
+            "type": "boolean"
+          }
+        }
+      },
+      "DeviceListResponse": {
+        "type": "object",
+        "required": [
+          "devices"
+        ],
+        "properties": {
+          "devices": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DeviceResponse"
+            }
+          }
+        }
+      },
+      "DeviceResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "platform",
+          "attestation_verified",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "platform": {
+            "type": "string"
+          },
+          "attestation_verified": {
+            "type": "boolean"
+          },
+          "last_used_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "CreateDeviceChallengeRequest": {
+        "type": "object",
+        "required": [
+          "action",
+          "target_id"
+        ],
+        "properties": {
+          "action": {
+            "type": "string",
+            "description": "The action this challenge authorizes (e.g. \"approve_transaction\")"
+          },
+          "target_id": {
+            "type": "string",
+            "description": "ID of the resource the action targets"
+          }
+        }
+      },
+      "DeviceChallengeResponse": {
+        "type": "object",
+        "required": [
+          "challenge_nonce",
+          "expires_at",
+          "action_bound_hash"
+        ],
+        "properties": {
+          "challenge_nonce": {
+            "type": "string"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "action_bound_hash": {
+            "type": "string",
+            "description": "SHA-256 binding the challenge to the requested action and target"
+          }
+        }
+      },
+      "AttestDeviceChallengeRequest": {
+        "type": "object",
+        "required": [
+          "challenge_nonce",
+          "signature"
+        ],
+        "properties": {
+          "challenge_nonce": {
+            "type": "string"
+          },
+          "signature": {
+            "type": "string",
+            "description": "Signature over the challenge nonce using the device's private key"
+          }
+        }
+      },
+      "AttestDeviceChallengeResponse": {
+        "type": "object",
+        "required": [
+          "step_up_token",
+          "expires_at"
+        ],
+        "properties": {
+          "step_up_token": {
+            "type": "string",
+            "description": "Short-lived token authorizing the bound action"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "RegisterPushTokenRequest": {
+        "type": "object",
+        "required": [
+          "token",
+          "platform"
+        ],
+        "properties": {
+          "token": {
+            "type": "string",
+            "description": "Push notification token from APNs or FCM"
+          },
+          "platform": {
+            "type": "string",
+            "enum": [
+              "apns",
+              "fcm"
+            ]
+          }
+        }
+      },
+      "DecideApprovalRequest": {
+        "type": "object",
+        "required": [
+          "decision"
+        ],
+        "properties": {
+          "decision": {
+            "type": "string",
+            "enum": [
+              "approve",
+              "reject"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "description": "Optional human-readable reason for the decision"
+          }
+        }
+      },
+      "ApprovalResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "org_id",
+          "user_id",
+          "action",
+          "target_type",
+          "target_id",
+          "risk_tier",
+          "status",
+          "summary",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "user_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "action": {
+            "type": "string"
+          },
+          "target_type": {
+            "type": "string"
+          },
+          "target_id": {
+            "type": "string"
+          },
+          "risk_tier": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 3
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "pending",
+              "approved",
+              "rejected",
+              "expired"
+            ]
+          },
+          "summary": {
+            "type": "object",
+            "description": "Structured summary of the action requiring approval"
+          },
+          "reason": {
+            "type": "string",
+            "nullable": true
+          },
+          "decision_reason": {
+            "type": "string",
+            "nullable": true
+          },
+          "decided_by": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "decided_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
       }
     }
   }