@1claw/openapi-spec 0.23.2 → 0.25.0

package/openapi.yaml

@@ -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,
         policy-based access control, agent identity, Intents API,
@@ -62,6 +62,8 @@ tags:
       description: Platform administration
     - 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)
 
@@ -446,6 +448,334 @@ paths:
                 "400":
                     $ref: "#/components/responses/BadRequest"
 
+    /v1/auth/set-password:
+        post:
+            tags: [Authentication]
+            summary: Set initial password for platform users
+            description: Only allowed when the user has no password set (platform_oidc users after claiming).
+            operationId: setPassword
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [password, password_confirm]
+                            properties:
+                                password:
+                                    type: string
+                                    minLength: 12
+                                password_confirm:
+                                    type: string
+            responses:
+                "200":
+                    description: Password set successfully
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    message:
+                                        type: string
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+
+    /v1/auth/change-email:
+        post:
+            tags: [Authentication]
+            summary: Request email change
+            description: Sends a 6-digit verification code to the new email address. Code expires in 10 minutes.
+            operationId: changeEmail
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [new_email]
+                            properties:
+                                new_email:
+                                    type: string
+                                    format: email
+            responses:
+                "200":
+                    description: Verification code sent
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    message:
+                                        type: string
+                                    new_email:
+                                        type: string
+                                    expires_in_seconds:
+                                        type: integer
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "409":
+                    description: Email already in use
+
+    /v1/auth/verify-email-change:
+        post:
+            tags: [Authentication]
+            summary: Verify email change with code
+            operationId: verifyEmailChange
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [code]
+                            properties:
+                                code:
+                                    type: string
+            responses:
+                "200":
+                    description: Email updated
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    message:
+                                        type: string
+                                    email:
+                                        type: string
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+
+    /v1/auth/passkeys/register/begin:
+        post:
+            tags: [Authentication]
+            summary: Begin passkey registration
+            description: Returns a WebAuthn challenge for creating a new passkey credential.
+            operationId: passkeyRegisterBegin
+            responses:
+                "200":
+                    description: Registration options
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    challenge:
+                                        type: string
+                                    rp_id:
+                                        type: string
+                                    rp_name:
+                                        type: string
+                                    user_id:
+                                        type: string
+                                    user_name:
+                                        type: string
+                                    user_display_name:
+                                        type: string
+                                    attestation:
+                                        type: string
+                                    authenticator_selection:
+                                        type: object
+
+    /v1/auth/passkeys/register/complete:
+        post:
+            tags: [Authentication]
+            summary: Complete passkey registration
+            operationId: passkeyRegisterComplete
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [credential_id, attestation_object, client_data_json]
+                            properties:
+                                credential_id:
+                                    type: string
+                                attestation_object:
+                                    type: string
+                                client_data_json:
+                                    type: string
+                                transports:
+                                    type: array
+                                    items:
+                                        type: string
+                                name:
+                                    type: string
+            responses:
+                "201":
+                    description: Passkey registered
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    passkey_id:
+                                        type: string
+                                        format: uuid
+                                    credential_id:
+                                        type: string
+
+    /v1/auth/passkeys/assert/begin:
+        post:
+            tags: [Authentication]
+            summary: Begin passkey authentication
+            operationId: passkeyAssertBegin
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                email:
+                                    type: string
+                                    format: email
+            responses:
+                "200":
+                    description: Assertion options
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    challenge:
+                                        type: string
+                                    rp_id:
+                                        type: string
+                                    timeout:
+                                        type: integer
+                                    user_verification:
+                                        type: string
+                                    allow_credentials:
+                                        type: array
+                                        items:
+                                            type: object
+
+    /v1/auth/passkeys/assert/complete:
+        post:
+            tags: [Authentication]
+            summary: Complete passkey authentication
+            operationId: passkeyAssertComplete
+            security: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [credential_id, authenticator_data, client_data_json, signature]
+                            properties:
+                                credential_id:
+                                    type: string
+                                authenticator_data:
+                                    type: string
+                                client_data_json:
+                                    type: string
+                                signature:
+                                    type: string
+            responses:
+                "200":
+                    description: Authentication successful
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    token:
+                                        type: string
+                                    refresh_token:
+                                        type: string
+                                    user:
+                                        type: object
+
+    /v1/auth/passkeys:
+        get:
+            tags: [Authentication]
+            summary: List registered passkeys
+            operationId: listPasskeys
+            responses:
+                "200":
+                    description: List of passkeys
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    passkeys:
+                                        type: array
+                                        items:
+                                            type: object
+                                            properties:
+                                                id:
+                                                    type: string
+                                                    format: uuid
+                                                credential_id:
+                                                    type: string
+                                                name:
+                                                    type: string
+                                                last_used_at:
+                                                    type: string
+                                                created_at:
+                                                    type: string
+
+    /v1/auth/passkeys/{passkey_id}:
+        delete:
+            tags: [Authentication]
+            summary: Delete a passkey
+            operationId: deletePasskey
+            parameters:
+                - name: passkey_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Passkey deleted
+
+    /v1/approvals/request:
+        post:
+            tags: [Approvals]
+            summary: Request human approval (agent-only)
+            description: Agents can request policy changes or other sensitive actions that require human approval.
+            operationId: requestApproval
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [action, target_type, target_id, summary]
+                            properties:
+                                action:
+                                    type: string
+                                    description: "Type of action (e.g. policy_change)"
+                                target_type:
+                                    type: string
+                                target_id:
+                                    type: string
+                                summary:
+                                    type: object
+                                    description: "JSON payload describing the request"
+                                reason:
+                                    type: string
+                                risk_tier:
+                                    type: integer
+                                    minimum: 1
+                                    maximum: 5
+            responses:
+                "202":
+                    description: Approval request created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ApprovalResponse"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
     /v1/auth/me:
         get:
             tags: [Authentication]
@@ -871,6 +1201,157 @@ paths:
                 "403":
                     $ref: "#/components/responses/Forbidden"
 
+    /v1/auth/devices:
+        post:
+            tags: [Authentication]
+            summary: Register a mobile device
+            description: |
+                Register a new mobile device for the authenticated user. Human-only.
+                The device public key is used for step-up authentication challenges.
+            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
+                a high-risk transaction). The device signs the challenge nonce to prove
+                possession of the private key.
+            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.
+                Returns a short-lived step-up token that can be used for the bound action.
+            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
+                so the server can send approval requests and alerts.
+            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"
+
     # ---------------------------------------------------------------------------
     # Vaults
     # ---------------------------------------------------------------------------
@@ -3780,6 +4261,108 @@ paths:
                 "410":
                     description: Claim token has expired
 
+    # --- Approvals ---
+
+    /v1/approvals:
+        get:
+            tags: [Approvals]
+            summary: List pending approvals
+            description: |
+                Returns approvals for the authenticated user's organization.
+                Human-only. Supports filtering by status and pagination.
+            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.
+                Human-only. The approval must be in `pending` status.
+            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
 # =============================================================================
@@ -7222,6 +7805,29 @@ components:
                             items:
                                 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
 
         ConnectedAppResponse:
             type: object
@@ -7306,3 +7912,185 @@ components:
                     nullable: true
                 dashboard_url:
                     type: string
+
+        # --- Mobile Companion App schemas ---
+
+        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