openapi: 3.0.1
info:
  title: Dfns Approvals ServiceAccounts 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: ServiceAccounts
  description: Machine identities and their access tokens.
paths:
  /auth/service-accounts:
    post:
      operationId: createServiceAccount
      tags:
      - ServiceAccounts
      summary: Create a service account
      description: Creates a machine identity (service account) with an access token used for server-to-server API access. Requires a User Action Signature.
      security:
      - BearerAuth: []
        AppId: []
        UserAction: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - publicKey
              properties:
                name:
                  type: string
                publicKey:
                  type: string
                permissionId:
                  type: string
      responses:
        '200':
          description: The created service account and its access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
    get:
      operationId: listServiceAccounts
      tags:
      - ServiceAccounts
      summary: List service accounts
      responses:
        '200':
          description: A list of service accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceAccount'
  /auth/service-accounts/{serviceAccountId}:
    get:
      operationId: getServiceAccount
      tags:
      - ServiceAccounts
      summary: Get a service account by id
      parameters:
      - in: path
        name: serviceAccountId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The service account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
    put:
      operationId: updateServiceAccount
      tags:
      - ServiceAccounts
      summary: Update a service account
      security:
      - BearerAuth: []
        AppId: []
        UserAction: []
      parameters:
      - in: path
        name: serviceAccountId
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated service account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
  /auth/service-accounts/{serviceAccountId}/activate:
    put:
      operationId: activateServiceAccount
      tags:
      - ServiceAccounts
      summary: Activate a service account
      security:
      - BearerAuth: []
        AppId: []
        UserAction: []
      parameters:
      - in: path
        name: serviceAccountId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The activated service account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
  /auth/service-accounts/{serviceAccountId}/deactivate:
    put:
      operationId: deactivateServiceAccount
      tags:
      - ServiceAccounts
      summary: Deactivate a service account
      security:
      - BearerAuth: []
        AppId: []
        UserAction: []
      parameters:
      - in: path
        name: serviceAccountId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The deactivated service account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
components:
  schemas:
    ServiceAccount:
      type: object
      properties:
        userInfo:
          type: object
          properties:
            userId:
              type: string
            username:
              type: string
            isActive:
              type: boolean
            isServiceAccount:
              type: boolean
        accessTokens:
          type: array
          items:
            type: object
  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).