@1claw/openapi-spec 0.22.2 → 0.23.1

package/openapi.yaml

@@ -62,6 +62,8 @@ tags:
       description: Platform administration
     - name: Health
       description: Service health checks
+    - name: Platform
+      description: Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)
 
 # =============================================================================
 # PATHS
@@ -1843,6 +1845,58 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /v1/agents/{agent_id}/signing-keys/{chain}/export:
+        post:
+            tags: [Signing Keys]
+            summary: Export a signing key (private key included)
+            description: |
+                Export the private key for an agent's signing key. Requires re-authentication
+                via the X-Auth-Confirm header containing the user's account password.
+                Human users only — agents cannot export keys.
+            operationId: exportSigningKey
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+                - name: chain
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Account password for re-authentication
+                  schema:
+                      type: string
+                      format: password
+            responses:
+                "200":
+                    description: Signing key exported successfully
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [chain, curve, public_key, private_key, key_version, agent_id]
+                                properties:
+                                    chain:
+                                        type: string
+                                    curve:
+                                        type: string
+                                    public_key:
+                                        type: string
+                                    address:
+                                        type: string
+                                    private_key:
+                                        type: string
+                                    key_version:
+                                        type: integer
+                                    agent_id:
+                                        type: string
+                                        format: uuid
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
     # ---------------------------------------------------------------------------
     # Unified Signing Intent
     # ---------------------------------------------------------------------------
@@ -2929,7 +2983,8 @@ paths:
             summary: Export the private key for a treasury wallet
             description: |
                 Returns the raw private key hex for the user's active wallet on
-                the given chain. Audit-logged as `treasury_wallet.export`.
+                the given chain. Requires re-authentication via the `X-Auth-Confirm`
+                header (account password). Audit-logged as `treasury_wallet.export`.
                 Human users only.
             operationId: exportTreasuryWallet
             security:
@@ -2940,6 +2995,13 @@ paths:
                   required: true
                   schema:
                       type: string
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Account password for re-authentication
+                  schema:
+                      type: string
+                      format: password
             responses:
                 "200":
                     description: Private key exported
@@ -3356,6 +3418,318 @@ paths:
                 "401":
                     description: Unauthorized
 
+    # --- Platform API ---
+
+    /v1/platform/apps:
+        post:
+            tags: [Platform]
+            summary: Register a platform app
+            description: Register a new platform app for building on top of 1Claw. Returns an API key (plt_ prefix) that must be saved immediately.
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreatePlatformAppRequest"
+            responses:
+                "201":
+                    description: Platform app created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformAppCreatedResponse"
+                "400":
+                    description: Invalid request
+                "403":
+                    description: Only human users can register platform apps
+        get:
+            tags: [Platform]
+            summary: List platform apps
+            description: List all platform apps in the organization.
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: List of platform apps
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    $ref: "#/components/schemas/PlatformAppResponse"
+
+    /v1/platform/apps/{appId}:
+        get:
+            tags: [Platform]
+            summary: Get platform app details
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Platform app details
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformAppResponse"
+                "404":
+                    description: Not found
+        patch:
+            tags: [Platform]
+            summary: Update platform app
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpdatePlatformAppRequest"
+            responses:
+                "200":
+                    description: Updated platform app
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformAppResponse"
+        delete:
+            tags: [Platform]
+            summary: Delete platform app
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Deleted
+                "403":
+                    description: Only human users can delete platform apps
+
+    /v1/platform/apps/{appId}/templates:
+        post:
+            tags: [Platform]
+            summary: Create bootstrap template
+            description: Create a template that defines what vault, agents, and policies to bootstrap for each connected user.
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateTemplateRequest"
+            responses:
+                "201":
+                    description: Template created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformTemplateResponse"
+        get:
+            tags: [Platform]
+            summary: List templates
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: List of templates
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    $ref: "#/components/schemas/PlatformTemplateResponse"
+
+    /v1/platform/users/upsert:
+        post:
+            tags: [Platform]
+            summary: Provision or look up a platform user
+            description: Upserts a user using either an OIDC subject_token (verified against the platform app's JWKS) or an email address. Returns the user handle and connection ID.
+            security:
+                - BearerAuth: []
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpsertPlatformUserRequest"
+            responses:
+                "200":
+                    description: Existing user found
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformUserResponse"
+                "201":
+                    description: New user created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/PlatformUserResponse"
+
+    /v1/platform/apps/{appId}/users:
+        get:
+            tags: [Platform]
+            summary: List connected users
+            description: List all users connected to this platform app.
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "200":
+                    description: Connected users
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    $ref: "#/components/schemas/PlatformConnectedUserResponse"
+
+    /v1/platform/connections/{connectionId}/bootstrap:
+        post:
+            tags: [Platform]
+            summary: Bootstrap resources for a connected user
+            description: Executes a template to create vault, agent, and policies for the connected user. Returns a claim URL and token for the user to claim their resources.
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/BootstrapRequest"
+            responses:
+                "201":
+                    description: Resources bootstrapped
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/BootstrapResponse"
+
+    /v1/platform/apps/{appId}/audit:
+        get:
+            tags: [Platform]
+            summary: Platform audit log
+            description: Returns audit events related to this platform app.
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: appId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - in: query
+                  name: limit
+                  schema:
+                      type: integer
+                      default: 50
+                - in: query
+                  name: offset
+                  schema:
+                      type: integer
+                      default: 0
+            responses:
+                "200":
+                    description: Audit events
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    events:
+                                        type: array
+                                        items:
+                                            type: object
+
+    /v1/platform/connected-apps:
+        get:
+            tags: [Platform]
+            summary: List connected apps (user side)
+            description: Returns platform apps connected to the calling user's account.
+            security:
+                - BearerAuth: []
+            responses:
+                "200":
+                    description: Connected apps
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    connected_apps:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/ConnectedAppResponse"
+
+    /v1/platform/connected-apps/{connectionId}:
+        delete:
+            tags: [Platform]
+            summary: Disconnect a platform app
+            description: Disconnect the calling user from a platform app.
+            security:
+                - BearerAuth: []
+            parameters:
+                - in: path
+                  name: connectionId
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Disconnected
+                "404":
+                    description: Connection not found
+
 # =============================================================================
 # COMPONENTS
 # =============================================================================
@@ -6512,3 +6886,315 @@ components:
                     enum: [healthy, degraded]
                 version:
                     type: string
+
+        # --- Platform API Schemas ---
+
+        CreatePlatformAppRequest:
+            type: object
+            required: [name, slug]
+            properties:
+                name:
+                    type: string
+                slug:
+                    type: string
+                    minLength: 3
+                    maxLength: 64
+                    pattern: "^[a-zA-Z0-9_-]+$"
+                description:
+                    type: string
+                oidc_jwks_url:
+                    type: string
+                    format: uri
+                oidc_issuer:
+                    type: string
+                    format: uri
+                oidc_audience:
+                    type: string
+                    description: Expected audience claim for OIDC token validation
+                redirect_uris:
+                    type: array
+                    items:
+                        type: string
+                        format: uri
+                billing_model:
+                    type: string
+                    enum: [platform_pays, user_pays, hybrid]
+                    default: platform_pays
+                auth_mode:
+                    type: string
+                    enum: [silent, user_signin, configurable]
+                    default: silent
+                max_connected_users:
+                    type: integer
+                    nullable: true
+
+        UpdatePlatformAppRequest:
+            type: object
+            properties:
+                name:
+                    type: string
+                description:
+                    type: string
+                logo_url:
+                    type: string
+                oidc_jwks_url:
+                    type: string
+                oidc_issuer:
+                    type: string
+                oidc_audience:
+                    type: string
+                    description: Expected audience claim for OIDC token validation
+                redirect_uris:
+                    type: array
+                    items:
+                        type: string
+                webhook_url:
+                    type: string
+                billing_model:
+                    type: string
+                    enum: [platform_pays, user_pays, hybrid]
+                auth_mode:
+                    type: string
+                    enum: [silent, user_signin, configurable]
+                max_connected_users:
+                    type: integer
+                    nullable: true
+                is_active:
+                    type: boolean
+
+        PlatformAppResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                name:
+                    type: string
+                slug:
+                    type: string
+                description:
+                    type: string
+                logo_url:
+                    type: string
+                    nullable: true
+                api_key_prefix:
+                    type: string
+                oidc_jwks_url:
+                    type: string
+                    nullable: true
+                oidc_issuer:
+                    type: string
+                    nullable: true
+                oidc_audience:
+                    type: string
+                    nullable: true
+                    description: Expected audience claim for OIDC token validation
+                redirect_uris:
+                    type: array
+                    items:
+                        type: string
+                webhook_url:
+                    type: string
+                    nullable: true
+                is_active:
+                    type: boolean
+                billing_model:
+                    type: string
+                auth_mode:
+                    type: string
+                max_connected_users:
+                    type: integer
+                    nullable: true
+                connected_users:
+                    type: integer
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+
+        PlatformAppCreatedResponse:
+            allOf:
+                - $ref: "#/components/schemas/PlatformAppResponse"
+                - type: object
+                  required: [api_key]
+                  properties:
+                      api_key:
+                          type: string
+                          description: The platform API key. Save immediately - it cannot be retrieved again.
+
+        CreateTemplateRequest:
+            type: object
+            required: [name, spec]
+            properties:
+                name:
+                    type: string
+                description:
+                    type: string
+                spec:
+                    type: object
+                    description: |
+                        Template specification defining vault, agents, policies, and signing keys to bootstrap.
+                        Top-level fields: `vault` (object with name, description), `agents` (array of agent specs
+                        with name, description, shroud_enabled, intents, shroud_config), `policies` (array with
+                        vault_ref, principal_ref, paths, permissions, conditions), and `signing_keys` (array of
+                        `{ chain }` objects — supported chains: ethereum, bitcoin, solana, xrp, cardano, tron).
+                        When `signing_keys` is present, HSM-backed signing keys are auto-provisioned for the
+                        bootstrapped agent.
+
+        PlatformTemplateResponse:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                platform_app_id:
+                    type: string
+                    format: uuid
+                name:
+                    type: string
+                description:
+                    type: string
+                version:
+                    type: integer
+                spec:
+                    type: object
+                is_active:
+                    type: boolean
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+
+        UpsertPlatformUserRequest:
+            type: object
+            properties:
+                subject_token:
+                    type: string
+                    description: OIDC JWT from the platform's IdP (verified against JWKS)
+                subject_token_type:
+                    type: string
+                    default: "urn:ietf:params:oauth:token-type:jwt"
+                email:
+                    type: string
+                    format: email
+                    description: Fallback when subject_token is not provided
+                display_name:
+                    type: string
+
+        PlatformUserResponse:
+            type: object
+            properties:
+                user_handle:
+                    type: string
+                    format: uuid
+                is_new:
+                    type: boolean
+                connection_id:
+                    type: string
+                    format: uuid
+                email:
+                    type: string
+
+        PlatformConnectedUserResponse:
+            type: object
+            properties:
+                connection_id:
+                    type: string
+                    format: uuid
+                user_id:
+                    type: string
+                    format: uuid
+                external_subject:
+                    type: string
+                status:
+                    type: string
+                vault_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                agent_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                created_at:
+                    type: string
+                    format: date-time
+                claimed_at:
+                    type: string
+                    format: date-time
+                    nullable: true
+
+        BootstrapRequest:
+            type: object
+            properties:
+                template_id:
+                    type: string
+                    format: uuid
+                    description: Template to use. Falls back to the app's default template.
+                return_to:
+                    type: string
+                    format: uri
+                    description: URL to redirect the user to after claiming resources.
+
+        BootstrapResponse:
+            type: object
+            properties:
+                claim_url:
+                    type: string
+                    format: uri
+                claim_token:
+                    type: string
+                expires_in:
+                    type: integer
+                    description: Seconds until the claim token expires
+                connection_id:
+                    type: string
+                    format: uuid
+                summary:
+                    type: object
+                    properties:
+                        vault_id:
+                            type: string
+                            format: uuid
+                            nullable: true
+                        agent_id:
+                            type: string
+                            format: uuid
+                            nullable: true
+                        policy_ids:
+                            type: array
+                            items:
+                                type: string
+                                format: uuid
+
+        ConnectedAppResponse:
+            type: object
+            properties:
+                connection_id:
+                    type: string
+                    format: uuid
+                app_name:
+                    type: string
+                app_slug:
+                    type: string
+                status:
+                    type: string
+                vault_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                agent_ids:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                created_at:
+                    type: string
+                    format: date-time