@1claw/openapi-spec 0.49.0 → 0.51.0

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
     title: 1Claw API
-    version: 2.36.0
+    version: 0.51.0
     description: |
         Secure secret management for AI agents. Provides vaults, secrets,
         policy-based access control, agent identity, Intents API,
@@ -110,6 +110,8 @@ tags:
       description: Sub-organization management
     - name: Portfolio
       description: Unified balance aggregator
+    - name: Environment Variables
+      description: Per-vault and org-shared environment variable management
 
 # =============================================================================
 # PATHS
@@ -625,7 +627,17 @@ paths:
         post:
             tags: [Authentication]
             summary: Complete passkey registration
+            description: |
+                When the account already has a password, passkey, or TOTP,
+                `X-Auth-Confirm` is required (purpose `security.passkey.register`).
             operationId: passkeyRegisterComplete
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: false
+                  description: Re-auth token (`rat_`) or account password
+                  schema:
+                      type: string
             requestBody:
                 required: true
                 content:
@@ -768,6 +780,12 @@ paths:
         delete:
             tags: [Authentication]
             summary: Delete a passkey
+            description: |
+                Removes a registered passkey. Requires recent re-authentication
+                (`X-Auth-Confirm` with a `rat_` token from `POST /v1/auth/reauth`
+                using purpose `security.passkey.delete`). Passkey or TOTP is
+                required when either is enrolled. Deleting the last passkey is
+                refused while vault passkey unlock is enabled.
             operationId: deletePasskey
             parameters:
                 - name: passkey_id
@@ -776,9 +794,17 @@ paths:
                   schema:
                       type: string
                       format: uuid
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Re-auth token (`rat_`) or account password
+                  schema:
+                      type: string
             responses:
                 "200":
                     description: Passkey deleted
+                "403":
+                    $ref: "#/components/responses/Forbidden"
 
     /v1/approvals/request:
         post:
@@ -861,6 +887,13 @@ paths:
             tags: [Authentication]
             summary: Delete current user account
             operationId: deleteMe
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  description: Re-auth token (`rat_`, purpose `account.delete`) or password
+                  schema:
+                      type: string
             requestBody:
                 required: true
                 content:
@@ -878,6 +911,52 @@ paths:
                 "400":
                     $ref: "#/components/responses/BadRequest"
 
+    /v1/auth/settings:
+        get:
+            tags: [Authentication]
+            summary: Get user security settings
+            operationId: getSecuritySettings
+            responses:
+                "200":
+                    description: Security settings
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    require_passkey_for_vaults:
+                                        type: boolean
+                                    passkey_count:
+                                        type: integer
+        patch:
+            tags: [Authentication]
+            summary: Update user security settings
+            description: |
+                Disabling `require_passkey_for_vaults` requires `X-Auth-Confirm`
+                (purpose `security.vault_passkey.disable`) with a passkey or TOTP
+                when either is enrolled.
+            operationId: updateSecuritySettings
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: false
+                  schema:
+                      type: string
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            properties:
+                                require_passkey_for_vaults:
+                                    type: boolean
+            responses:
+                "200":
+                    description: Updated settings
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+
     # MFA
 
     /v1/auth/mfa/status:
@@ -953,7 +1032,18 @@ paths:
         delete:
             tags: [Authentication]
             summary: Disable MFA
+            description: |
+                Requires a valid TOTP or recovery code in the body, or a passkey
+                re-auth token in `X-Auth-Confirm` (purpose `security.mfa.disable`).
+                Account password alone is not accepted while TOTP is enabled.
             operationId: mfaDisable
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: false
+                  description: Passkey or TOTP re-auth token (`rat_`)
+                  schema:
+                      type: string
             requestBody:
                 required: true
                 content:
@@ -1118,8 +1208,15 @@ paths:
                 Returns a full export of the authenticated user's data including
                 profile, vaults, agents, secrets metadata, and policies. Intended
                 for GDPR data-portability requests. Only available to human users
-                (not agents).
+                (not agents). Requires `X-Auth-Confirm` (purpose `account.export`);
+                passkey or TOTP when either is enrolled.
             operationId: exportUserData
+            parameters:
+                - name: X-Auth-Confirm
+                  in: header
+                  required: true
+                  schema:
+                      type: string
             responses:
                 "200":
                     description: User data export
@@ -1889,6 +1986,216 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    # ---------------------------------------------------------------------------
+    # Environment Variables (per-vault)
+    # ---------------------------------------------------------------------------
+
+    /v1/vaults/{vault_id}/env-vars:
+        get:
+            tags: [Environment Variables]
+            summary: List environment variables
+            description: List all environment variables for a vault, optionally filtered by environment.
+            operationId: listEnvVars
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - name: environment
+                  in: query
+                  schema:
+                      type: string
+                  description: Filter by environment (production, preview, development, or custom)
+            responses:
+                "200":
+                    description: Environment variable list
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    env_vars:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/EnvVar"
+        post:
+            tags: [Environment Variables]
+            summary: Create environment variable
+            operationId: createEnvVar
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateEnvVarRequest"
+            responses:
+                "201":
+                    description: Environment variable created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EnvVar"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+
+    /v1/vaults/{vault_id}/env-vars/resolve:
+        get:
+            tags: [Environment Variables]
+            summary: Resolve environment variables
+            description: Resolve the final KEY=VALUE set for an environment with full precedence (shared < vault < branch override).
+            operationId: resolveEnvVars
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - name: environment
+                  in: query
+                  required: true
+                  schema:
+                      type: string
+                - name: git_branch
+                  in: query
+                  schema:
+                      type: string
+            responses:
+                "200":
+                    description: Resolved environment variables
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ResolveEnvVarsResponse"
+
+    /v1/vaults/{vault_id}/env-vars/{key}:
+        get:
+            tags: [Environment Variables]
+            summary: Get environment variable
+            operationId: getEnvVar
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - name: key
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                - name: environment
+                  in: query
+                  schema:
+                      type: string
+            responses:
+                "200":
+                    description: Environment variable
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EnvVar"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        patch:
+            tags: [Environment Variables]
+            summary: Update environment variable
+            operationId: updateEnvVar
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - name: key
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                - name: environment
+                  in: query
+                  schema:
+                      type: string
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpdateEnvVarRequest"
+            responses:
+                "200":
+                    description: Environment variable updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/EnvVar"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+        delete:
+            tags: [Environment Variables]
+            summary: Delete environment variable
+            operationId: deleteEnvVar
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - name: key
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                - name: environment
+                  in: query
+                  schema:
+                      type: string
+            responses:
+                "204":
+                    description: Deleted
+
+    # ---------------------------------------------------------------------------
+    # Vault Environments
+    # ---------------------------------------------------------------------------
+
+    /v1/vaults/{vault_id}/environments:
+        get:
+            tags: [Environment Variables]
+            summary: List vault environments
+            operationId: listVaultEnvironments
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+            responses:
+                "200":
+                    description: Vault environment list
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    environments:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/VaultEnvironment"
+        post:
+            tags: [Environment Variables]
+            summary: Create custom environment
+            operationId: createVaultEnvironment
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateEnvironmentRequest"
+            responses:
+                "201":
+                    description: Environment created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/VaultEnvironment"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+
+    /v1/vaults/{vault_id}/environments/{slug}:
+        delete:
+            tags: [Environment Variables]
+            summary: Delete custom environment
+            operationId: deleteVaultEnvironment
+            parameters:
+                - $ref: "#/components/parameters/VaultId"
+                - name: slug
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            responses:
+                "204":
+                    description: Deleted
+
     # ---------------------------------------------------------------------------
     # Agent Self-Enrollment (public)
     # ---------------------------------------------------------------------------
@@ -3388,6 +3695,138 @@ paths:
                 "204":
                     description: Member removed
 
+    # ---------------------------------------------------------------------------
+    # Org Shared Environment Variables
+    # ---------------------------------------------------------------------------
+
+    /v1/org/env-vars:
+        get:
+            tags: [Organization]
+            summary: List org shared environment variables
+            operationId: listOrgEnvVars
+            responses:
+                "200":
+                    description: Org shared environment variable list
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                properties:
+                                    env_vars:
+                                        type: array
+                                        items:
+                                            $ref: "#/components/schemas/OrgEnvVar"
+        post:
+            tags: [Organization]
+            summary: Create org shared environment variable
+            operationId: createOrgEnvVar
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/CreateOrgEnvVarRequest"
+            responses:
+                "201":
+                    description: Org shared env var created
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OrgEnvVar"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+
+    /v1/org/env-vars/{key}:
+        patch:
+            tags: [Organization]
+            summary: Update org shared environment variable
+            operationId: updateOrgEnvVar
+            parameters:
+                - name: key
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            requestBody:
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/UpdateOrgEnvVarRequest"
+            responses:
+                "200":
+                    description: Org shared env var updated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OrgEnvVar"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/org/env-vars/{id}:
+        delete:
+            tags: [Organization]
+            summary: Delete org shared environment variable
+            operationId: deleteOrgEnvVar
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Deleted
+
+    /v1/org/env-vars/{id}/link:
+        post:
+            tags: [Organization]
+            summary: Link org shared env var to a vault
+            operationId: linkOrgEnvVar
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+                            required: [vault_id]
+                            properties:
+                                vault_id:
+                                    type: string
+                                    format: uuid
+            responses:
+                "201":
+                    description: Linked
+
+    /v1/org/env-vars/{id}/links/{vault_id}:
+        delete:
+            tags: [Organization]
+            summary: Unlink org shared env var from a vault
+            operationId: unlinkOrgEnvVar
+            parameters:
+                - name: id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+                - name: vault_id
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+                      format: uuid
+            responses:
+                "204":
+                    description: Unlinked
+
     # ---------------------------------------------------------------------------
     # Billing
     # ---------------------------------------------------------------------------
@@ -10278,8 +10717,11 @@ components:
             properties:
                 code:
                     type: string
+                    description: TOTP or recovery code
                 password:
                     type: string
+                    description: Deprecated. Password is no longer sufficient to disable MFA.
+                    deprecated: true
 
         # --- Device Auth ---
 
@@ -15825,6 +16267,9 @@ components:
                     type: string
                 image:
                     type: string
+                environment:
+                    type: string
+                    description: Vault environment to resolve env vars from (e.g. production, preview, development)
                 env_public:
                     type: object
                     additionalProperties:
@@ -15861,6 +16306,9 @@ components:
                     type: string
                 image:
                     type: string
+                environment:
+                    type: string
+                    description: Vault environment to resolve env vars from
                 env_public:
                     type: object
                     additionalProperties:
@@ -15910,6 +16358,10 @@ components:
                 image:
                     type: string
                     nullable: true
+                environment:
+                    type: string
+                    nullable: true
+                    description: Vault environment for env var resolution
                 env_public:
                     type: object
                     additionalProperties:
@@ -17109,7 +17561,33 @@ components:
                     type: string
                 value_above:
                     type: string
-                    description: Native value threshold in gwei
+                    description: Native value threshold in wei (arbitrary-precision string)
+                eip712_primary_type_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-712 typed_data primaryType (case-sensitive)
+                eip712_verifying_contract_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-712 domain.verifyingContract (case-insensitive)
+                eip712_domain_name_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-712 domain.name
+                eip712_domain_chain_id_in:
+                    type: array
+                    items:
+                        type: integer
+                        format: int64
+                    description: Match EIP-712 domain.chainId
+                eip7702_authorized_addresses_in:
+                    type: array
+                    items:
+                        type: string
+                    description: Match EIP-7702 authorization_list delegate addresses (case-insensitive)
                 to_address_in:
                     type: array
                     items:
@@ -17240,14 +17718,19 @@ components:
         ConsensusCondition:
             oneOf:
                 - type: object
-                  required: [type, threshold_gwei]
+                  required: [type]
                   properties:
                       type:
                           type: string
                           enum: [value_above]
+                      threshold_wei:
+                          type: string
+                          description: Value threshold in wei (arbitrary-precision string). Preferred over threshold_gwei.
                       threshold_gwei:
                           type: integer
                           format: int64
+                          deprecated: true
+                          description: Deprecated — use threshold_wei for arbitrary precision
                 - type: object
                   required: [type, chains]
                   properties:
@@ -17302,6 +17785,19 @@ components:
                       type:
                           type: string
                           enum: [always]
+                - type: object
+                  required: [type, actions]
+                  properties:
+                      type:
+                          type: string
+                          enum: [action_in]
+                      actions:
+                          type: array
+                          items:
+                              type: string
+                          description: |
+                              Control-plane actions to match, e.g. policy.create, policy.update,
+                              policy.delete, signing_key.export, member.role_change, member.remove
 
         ApprovalRequirement:
             type: object
@@ -17317,6 +17813,12 @@ components:
                     type: object
                     additionalProperties:
                         type: integer
+                require_credential_types:
+                    type: array
+                    items:
+                        type: string
+                        enum: [password, passkey, totp, biometric, api_key]
+                    description: At least one approval must use one of these credential types
 
         SubmitPendingApprovalRequest:
             type: object
@@ -17359,6 +17861,10 @@ components:
                     type: string
                 reason:
                     type: string
+                credential_type:
+                    type: string
+                    enum: [password, passkey, totp, biometric, api_key]
+                    description: Authentication method used for this approval vote
 
         PendingApprovalResponse:
             type: object
@@ -17621,3 +18127,201 @@ components:
                 created_at:
                     type: string
                     format: date-time
+
+        # -------------------------------------------------------------------
+        # Environment Variables
+        # -------------------------------------------------------------------
+
+        EnvVar:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                key:
+                    type: string
+                environments:
+                    type: array
+                    items:
+                        type: string
+                git_branch:
+                    type: string
+                    nullable: true
+                sensitive:
+                    type: boolean
+                comment:
+                    type: string
+                    nullable: true
+                value:
+                    type: string
+                    nullable: true
+                    description: Null for sensitive vars in list responses
+                version:
+                    type: integer
+                created_by:
+                    type: string
+                    nullable: true
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+
+        CreateEnvVarRequest:
+            type: object
+            required: [key, value]
+            properties:
+                key:
+                    type: string
+                    description: Uppercase alphanumeric + underscore, 1-256 chars
+                value:
+                    type: string
+                environments:
+                    type: array
+                    items:
+                        type: string
+                    default: [production, preview, development]
+                git_branch:
+                    type: string
+                    description: Branch override (preview only)
+                sensitive:
+                    type: boolean
+                    default: false
+                comment:
+                    type: string
+
+        UpdateEnvVarRequest:
+            type: object
+            properties:
+                value:
+                    type: string
+                environments:
+                    type: array
+                    items:
+                        type: string
+                sensitive:
+                    type: boolean
+                comment:
+                    type: string
+
+        ResolveEnvVarsResponse:
+            type: object
+            properties:
+                vars:
+                    type: object
+                    additionalProperties:
+                        type: string
+                sources:
+                    type: object
+                    additionalProperties:
+                        type: string
+                        enum: [shared, vault, branch_override]
+                environment:
+                    type: string
+                git_branch:
+                    type: string
+                    nullable: true
+                resolved_at:
+                    type: string
+                    format: date-time
+
+        VaultEnvironment:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                slug:
+                    type: string
+                description:
+                    type: string
+                    nullable: true
+                is_builtin:
+                    type: boolean
+                copied_from:
+                    type: string
+                    nullable: true
+                is_detached:
+                    type: boolean
+                created_at:
+                    type: string
+                    format: date-time
+
+        CreateEnvironmentRequest:
+            type: object
+            required: [slug]
+            properties:
+                slug:
+                    type: string
+                    description: Lowercase alphanumeric + hyphens, 2-30 chars
+                description:
+                    type: string
+                copy_from:
+                    type: string
+                    description: Copy env vars from this environment
+
+        OrgEnvVar:
+            type: object
+            properties:
+                id:
+                    type: string
+                    format: uuid
+                key:
+                    type: string
+                environments:
+                    type: array
+                    items:
+                        type: string
+                sensitive:
+                    type: boolean
+                comment:
+                    type: string
+                    nullable: true
+                value:
+                    type: string
+                    nullable: true
+                version:
+                    type: integer
+                linked_vaults:
+                    type: array
+                    items:
+                        type: string
+                        format: uuid
+                created_at:
+                    type: string
+                    format: date-time
+                updated_at:
+                    type: string
+                    format: date-time
+
+        CreateOrgEnvVarRequest:
+            type: object
+            required: [key, value]
+            properties:
+                key:
+                    type: string
+                value:
+                    type: string
+                environments:
+                    type: array
+                    items:
+                        type: string
+                    default: [production, preview, development]
+                sensitive:
+                    type: boolean
+                    default: false
+                comment:
+                    type: string
+
+        UpdateOrgEnvVarRequest:
+            type: object
+            properties:
+                value:
+                    type: string
+                environments:
+                    type: array
+                    items:
+                        type: string
+                comment:
+                    type: string