openapi: 3.0.1
info:
  title: Corbado Backend ConnectTokens API
  description: The Corbado Backend API is a server-to-server REST API for the Corbado passkey-first authentication platform. It manages users, login identifiers, sessions, passkeys (WebAuthn credentials), passkey events, Connect tokens, and project data exports. Requests authenticate with HTTP Basic auth using the project ID as username and the API secret as password (both obtained from the Corbado Developer Panel).
  termsOfService: https://www.corbado.com/legal/terms
  contact:
    name: Corbado Support
    url: https://docs.corbado.com
    email: support@corbado.com
  version: 2.0.0
servers:
- url: https://backendapi.corbado.io/v2
  description: Corbado Backend API v2
security:
- basicAuth: []
tags:
- name: ConnectTokens
  description: Short-lived tokens authorizing Corbado Connect frontend flows.
paths:
  /connectTokens:
    post:
      operationId: connectTokenCreate
      tags:
      - ConnectTokens
      summary: Create ConnectToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectTokenCreateReq'
      responses:
        '200':
          description: The created Connect token, including its secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectToken'
        '400':
          $ref: '#/components/responses/ErrorRsp'
    get:
      operationId: connectTokenList
      tags:
      - ConnectTokens
      summary: List ConnectTokens
      parameters:
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of Connect tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectTokenList'
        '401':
          $ref: '#/components/responses/ErrorRsp'
  /connectTokens/{connectTokenID}:
    parameters:
    - name: connectTokenID
      in: path
      required: true
      schema:
        type: string
    patch:
      operationId: connectTokenUpdate
      tags:
      - ConnectTokens
      summary: Update ConnectToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectTokenUpdateReq'
      responses:
        '200':
          description: The updated Connect token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectToken'
        '404':
          $ref: '#/components/responses/ErrorRsp'
    delete:
      operationId: connectTokenDelete
      tags:
      - ConnectTokens
      summary: Delete ConnectToken
      responses:
        '200':
          description: The Connect token was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericRsp'
        '404':
          $ref: '#/components/responses/ErrorRsp'
components:
  schemas:
    ErrorRsp:
      type: object
      required:
      - httpStatusCode
      - message
      properties:
        httpStatusCode:
          type: integer
          format: int32
        message:
          type: string
        requestData:
          $ref: '#/components/schemas/RequestData'
        runtime:
          type: number
          format: float
        error:
          type: object
          properties:
            type:
              type: string
            details:
              type: string
            validation:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
    ConnectTokenCreateReq:
      type: object
      required:
      - connectTokenType
      properties:
        connectTokenType:
          type: string
          enum:
          - passkey-append
          - passkey-delete
          - passkey-list
        identifierValue:
          type: string
        data:
          type: string
          description: Opaque application-specific data carried with the token.
    GenericRsp:
      type: object
      properties:
        httpStatusCode:
          type: integer
          format: int32
        message:
          type: string
        requestData:
          $ref: '#/components/schemas/RequestData'
        runtime:
          type: number
          format: float
    ConnectTokenUpdateReq:
      type: object
      properties:
        status:
          type: string
    RequestData:
      type: object
      properties:
        requestID:
          type: string
        link:
          type: string
    ConnectToken:
      type: object
      required:
      - connectTokenID
      - connectTokenType
      properties:
        connectTokenID:
          type: string
        connectTokenType:
          type: string
          enum:
          - passkey-append
          - passkey-delete
          - passkey-list
        secret:
          type: string
          description: The token secret returned only on creation, passed to the Corbado Connect frontend component.
        identifierValue:
          type: string
        status:
          type: string
        created:
          type: string
          format: date-time
    Paging:
      type: object
      properties:
        page:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
        totalItems:
          type: integer
          format: int32
    ConnectTokenList:
      type: object
      required:
      - connectTokens
      - paging
      properties:
        connectTokens:
          type: array
          items:
            $ref: '#/components/schemas/ConnectToken'
        paging:
          $ref: '#/components/schemas/Paging'
  parameters:
    Sort:
      name: sort
      in: query
      required: false
      description: Field and direction to sort by, e.g. created:desc.
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 10
    Filter:
      name: filter
      in: query
      required: false
      description: Repeatable filter expressions, e.g. status:eq:active.
      schema:
        type: array
        items:
          type: string
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 1
  responses:
    ErrorRsp:
      description: An error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorRsp'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. The username is the project ID (e.g. pro-1234567890) and the password is the API secret, both issued from the Corbado Developer Panel.