openapi: 3.0.1
info:
  title: Dfns Approvals Keys API
  description: 'Representative OpenAPI description of the Dfns wallet-as-a-service and MPC key-management REST API. Covers programmable non-custodial wallets, MPC keys, transfers and transactions, signature generation, the policy engine and approvals, webhooks, permissions and authentication (including User Action Signing), service accounts, and blockchain network reads.

    Authentication uses an Authorization Bearer access token (from a service account token or a user login) plus, for sensitive mutating operations, a User Action Signature obtained via the User Action Signing challenge/complete flow and passed in the X-DFNS-USERACTION header.'
  contact:
    name: Dfns Support
    url: https://www.dfns.co/
  termsOfService: https://www.dfns.co/terms-of-service
  version: '1.0'
servers:
- url: https://api.dfns.io
  description: Dfns production REST API (Europe / default)
- url: https://api.uae.dfns.io
  description: Dfns production REST API (UAE region)
security:
- BearerAuth: []
  AppId: []
tags:
- name: Keys
  description: Standalone MPC keys and delegated signing.
paths:
  /keys:
    post:
      operationId: createKey
      tags:
      - Keys
      summary: Create a key
      description: Creates a standalone MPC key (scheme/curve) not bound to a single network, usable to derive addresses across chains. Requires a User Action Signature.
      security:
      - BearerAuth: []
        AppId: []
        UserAction: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - scheme
              - curve
              properties:
                scheme:
                  type: string
                  example: ECDSA
                curve:
                  type: string
                  example: secp256k1
                name:
                  type: string
      responses:
        '200':
          description: The created key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
    get:
      operationId: listKeys
      tags:
      - Keys
      summary: List keys
      responses:
        '200':
          description: A list of keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Key'
                  nextPageToken:
                    type: string
                    nullable: true
  /keys/{keyId}:
    get:
      operationId: getKey
      tags:
      - Keys
      summary: Get a key by id
      parameters:
      - in: path
        name: keyId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
  /keys/{keyId}/delegate:
    post:
      operationId: delegateKey
      tags:
      - Keys
      summary: Delegate a key to an end user
      description: Transfers control of a key (and its wallets) to an end user's credentials, enabling non-custodial delegated signing. Requires a User Action Signature.
      security:
      - BearerAuth: []
        AppId: []
        UserAction: []
      parameters:
      - in: path
        name: keyId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - userId
              properties:
                userId:
                  type: string
      responses:
        '200':
          description: The delegated key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
components:
  schemas:
    Key:
      type: object
      properties:
        id:
          type: string
          example: key-2s7vg-...
        scheme:
          type: string
          example: ECDSA
        curve:
          type: string
          example: secp256k1
        publicKey:
          type: string
        status:
          type: string
          enum:
          - Active
          - Archived
        custodial:
          type: boolean
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Access token issued to a service account or a logged-in user. Sent as `Authorization: Bearer <token>`.'
    AppId:
      type: apiKey
      in: header
      name: X-DFNS-APPID
      description: The Dfns application (app) id the request is made on behalf of.
    UserAction:
      type: apiKey
      in: header
      name: X-DFNS-USERACTION
      description: A User Action Signature token proving the caller cryptographically signed the request payload. Required on sensitive mutating operations (transfers, signature generation, key/policy/permission changes).