Stellar API Keys API

openapi: 3.2.0
info:
  title: Stellar Disbursement Platform API Keys API
  version: 2.1.0
  summary: The Stellar Disbursement Platform (SDP) is a tool built for organizations to make bulk payments to a group of recipients over the Stellar network.
  description: 'The Stellar Disbursement Platform (SDP) is a tool built for organizations to make bulk payments to a group of recipients over the Stellar network.


    This is an open-source project that is built on top of the Stellar network, and the code can be found on the following repositories:


    - [stellar/stellar-disbursement-platform-backend](https://github.com/stellar/stellar-disbursement-platform-backend): This repository contains the backend and infrastructure code for the Stellar Disbursement Platform.

    - [stellar/stellar-disbursement-platform-frontend](https://github.com/stellar/stellar-disbursement-platform-frontend): This repository contains the web frontend code for the Stellar Disbursement Platform.

    - [stellar/helm-charts](https://github.com/stellar/helm-charts/tree/main/charts/stellar-disbursement-platform): This repository contains the Helm chart for deploying the Stellar Disbursement Platform using kubernetes.

    '
  termsOfService: https://stellar.org/terms-of-service
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: ''
tags:
- name: API Keys
  description: API Keys functionality allows to create access key with granular permissions and resource management.
paths:
  /api-keys:
    get:
      tags:
      - API Keys
      summary: List API Keys
      description: Retrieves all API keys created by the current user. The results are ordered by creation date in descending order (most recent first). API key values are not included in the response for security reasons.
      operationId: ListAPIKeys
      responses:
        '200':
          description: API keys retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIKey'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
      security:
      - BearerAuth: []
    post:
      tags:
      - API Keys
      summary: Create API Key
      description: Creates a new API Key to access SDP endpoints. API Key can be configured to have a granular read/write access, also API key can be restricted to the specific IP or range of the IPs.
      operationId: CreateAPIKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAPIKeyRequest'
        required: true
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAPIKeyResponse'
        '400':
          description: Bad request - validation errors
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
      security:
      - BearerAuth: []
  /api-keys/{id}:
    get:
      tags:
      - API Keys
      summary: Get API Key Details
      description: Retrieves a specific API key by its ID. Returns the API key details including permissions and restrictions, but does not include the actual key value for security reasons.
      operationId: GetAPIKey
      parameters:
      - name: id
        in: path
        description: The unique identifier of the API key
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKey'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          description: API key not found
          $ref: '#/components/responses/NotFoundResponse'
      security:
      - BearerAuth: []
    patch:
      tags:
      - API Keys
      summary: Update API Key
      description: Updates an existing API key's permissions and IP restrictions. The API key name and expiration date cannot be modified after creation.
      operationId: UpdateAPIKey
      parameters:
      - name: id
        in: path
        description: The unique identifier of the API key to update
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAPIKeyRequest'
        required: true
      responses:
        '200':
          description: API key updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKey'
        '400':
          description: Bad request - validation errors
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          description: API key not found
          $ref: '#/components/responses/NotFoundResponse'
      security:
      - BearerAuth: []
    delete:
      tags:
      - API Keys
      summary: Delete API Key
      description: Permanently deletes an API key. This action cannot be undone. Once deleted, the API key will no longer be able to authenticate API requests.
      operationId: DeleteAPIKey
      parameters:
      - name: id
        in: path
        description: The unique identifier of the API key to delete
        required: true
        schema:
          type: string
      responses:
        '204':
          description: API key deleted successfully
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          description: API key not found
          $ref: '#/components/responses/NotFoundResponse'
      security:
      - BearerAuth: []
components:
  schemas:
    UpdateAPIKeyRequest:
      type: object
      required:
      - permissions
      properties:
        permissions:
          type: array
          description: List of permissions granted to this API key
          items:
            type: string
            enum:
            - read:all
            - write:all
            - read:disbursements
            - write:disbursements
            - read:receivers
            - write:receivers
            - read:payments
            - write:payments
            - read:organization
            - write:organization
            - read:users
            - write:users
            - read:wallets
            - write:wallets
            - read:statistics
            - read:exports
          minItems: 1
        allowed_ips:
          oneOf:
          - type: string
            description: Single IP address or CIDR range
          - type: array
            items:
              type: string
            description: Array of IP addresses or CIDR ranges
          description: IP restrictions for the API key. If not provided, existing restrictions remain unchanged
    CreateAPIKeyResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the API key
        name:
          type: string
          description: Human-readable name for the API key
        key:
          type: string
          description: The actual API key (only returned once at creation)
        permissions:
          type: array
          items:
            type: string
          description: List of permissions granted to this API key
        allowed_ips:
          type: array
          items:
            type: string
          description: List of allowed IP addresses or CIDR ranges
        expiry_date:
          type: string
          format: date-time
          description: Expiration date of the API key
        created_at:
          type: string
          format: date-time
          description: When the API key was created
        created_by:
          type: string
          description: User who created the API key
        updated_at:
          type: string
          format: date-time
          description: When the API key was last updated
        updated_by:
          type: string
          description: User who last updated the API key
        last_used_at:
          type: string
          format: date-time
          description: When the API key was last used
    APIKey:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the API key
        name:
          type: string
          description: Human-readable name for the API key
        permissions:
          type: array
          items:
            type: string
          description: List of permissions granted to this API key
        allowed_ips:
          type: array
          items:
            type: string
          description: List of allowed IP addresses or CIDR ranges
        expiry_date:
          type: string
          format: date-time
          description: Expiration date of the API key
        created_at:
          type: string
          format: date-time
          description: When the API key was created
        created_by:
          type: string
          description: User who created the API key
        updated_at:
          type: string
          format: date-time
          description: When the API key was last updated
        updated_by:
          type: string
          description: User who last updated the API key
        last_used_at:
          type: string
          format: date-time
          description: When the API key was last used
    CreateAPIKeyRequest:
      type: object
      required:
      - name
      - permissions
      properties:
        name:
          type: string
          description: Human-readable name for the API key
        permissions:
          type: array
          description: List of permissions granted to this API key
          items:
            type: string
            enum:
            - read:all
            - write:all
            - read:disbursements
            - write:disbursements
            - read:receivers
            - write:receivers
            - read:payments
            - write:payments
            - read:organization
            - write:organization
            - read:users
            - write:users
            - read:wallets
            - write:wallets
            - read:statistics
            - read:exports
          minItems: 1
        expiry_date:
          type: string
          format: date-time
          description: Optional expiration date for the API key (must be in the future)
        allowed_ips:
          oneOf:
          - type: string
            description: Single IP address or CIDR range
          - type: array
            items:
              type: string
            description: Array of IP addresses or CIDR ranges
          description: IP restrictions for the API key. If not provided, the key can be used from any IP
  responses:
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              extras:
                type: object
                properties:
                  status:
                    type: number
                  message:
                    type: string
          example:
            error: Not authorized
            extras:
              status: 401
              message: Not authorized
    BadRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Details about the error
              extras:
                type: object
                properties: {}
    NotFoundResponse:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              extras:
                type: object
                properties:
                  status:
                    type: number
                  message:
                    type: string
          example:
            error: Not found
            extras:
              status: 404
              message: Resource not found
    ForbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          example:
            error: Forbidden
  securitySchemes:
    BearerAuth:
      type: apiKey
      description: Authorization header containing an SDP JWT (ES256) or an SDP_ API key.
      name: Authorization
      in: header
    SEP10Auth:
      type: apiKey
      description: Authorization header containing a SEP-10 JWT (Bearer {token}).
      name: Authorization
      in: header
    SEP24Auth:
      type: apiKey
      description: Authorization header containing a SEP-24 JWT (Bearer {token}).
      name: Authorization
      in: header
    SEP24QueryAuth:
      type: apiKey
      description: Query parameter containing a SEP-24 JWT.
      name: token
      in: query
x-original-swagger-version: '2.0'