openapi: 3.0.1
info:
  title: Corbado Backend 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: Users
    description: Create and manage end users and their social logins and credentials.
  - name: Identifiers
    description: Manage login identifiers (email, phone, username) attached to a user.
  - name: Sessions
    description: List and revoke authenticated sessions.
  - name: Passkeys
    description: WebAuthn passkey registration and login ceremonies and verification.
  - name: PasskeyEvents
    description: Record and query passkey lifecycle events for a user.
  - name: ConnectTokens
    description: Short-lived tokens authorizing Corbado Connect frontend flows.
  - name: Exports
    description: Project data exports and download links.
paths:
  /users:
    post:
      operationId: userCreate
      tags:
        - Users
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateReq'
      responses:
        '200':
          description: The created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ErrorRsp'
        '401':
          $ref: '#/components/responses/ErrorRsp'
    get:
      operationId: userList
      tags:
        - Users
      summary: List users
      parameters:
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/ErrorRsp'
  /users/{userID}:
    parameters:
      - $ref: '#/components/parameters/UserID'
    get:
      operationId: userGet
      tags:
        - Users
      summary: Retrieve a user
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/ErrorRsp'
    patch:
      operationId: userUpdate
      tags:
        - Users
      summary: Update a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateReq'
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/ErrorRsp'
    delete:
      operationId: userDelete
      tags:
        - Users
      summary: Delete a user
      responses:
        '200':
          description: The user was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericRsp'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /users/{userID}/credentials:
    parameters:
      - $ref: '#/components/parameters/UserID'
    get:
      operationId: userCredentialList
      tags:
        - Users
      summary: List passkeys for user
      responses:
        '200':
          description: The user's passkey credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialList'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /users/{userID}/credentials/{credentialID}:
    parameters:
      - $ref: '#/components/parameters/UserID'
      - name: credentialID
        in: path
        required: true
        schema:
          type: string
    delete:
      operationId: userCredentialDelete
      tags:
        - Users
      summary: Delete passkey
      responses:
        '200':
          description: The passkey credential was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericRsp'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /users/{userID}/identifiers:
    parameters:
      - $ref: '#/components/parameters/UserID'
    post:
      operationId: identifierCreate
      tags:
        - Identifiers
      summary: Create login identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifierCreateReq'
      responses:
        '200':
          description: The created login identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identifier'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /users/{userID}/identifiers/{identifierID}:
    parameters:
      - $ref: '#/components/parameters/UserID'
      - name: identifierID
        in: path
        required: true
        schema:
          type: string
    patch:
      operationId: identifierUpdate
      tags:
        - Identifiers
      summary: Update identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifierUpdateReq'
      responses:
        '200':
          description: The updated identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identifier'
        '404':
          $ref: '#/components/responses/ErrorRsp'
    delete:
      operationId: identifierDelete
      tags:
        - Identifiers
      summary: Delete identifier
      responses:
        '200':
          description: The identifier was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericRsp'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /identifiers:
    get:
      operationId: identifierList
      tags:
        - Identifiers
      summary: List all login identifiers
      parameters:
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of login identifiers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifierList'
        '401':
          $ref: '#/components/responses/ErrorRsp'
  /sessions:
    get:
      operationId: sessionList
      tags:
        - Sessions
      summary: List all sessions
      parameters:
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: A paged list of sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionList'
        '401':
          $ref: '#/components/responses/ErrorRsp'
  /sessions/{sessionID}/revoke:
    parameters:
      - name: sessionID
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: sessionRevoke
      tags:
        - Sessions
      summary: Revoke a session
      responses:
        '200':
          description: The session was revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericRsp'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /passkey/append/start:
    post:
      operationId: passkeyAppendStart
      tags:
        - Passkeys
      summary: Start creating passkey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyAppendStartReq'
      responses:
        '200':
          description: WebAuthn credential creation options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyStartRsp'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /passkey/append/finish:
    post:
      operationId: passkeyAppendFinish
      tags:
        - Passkeys
      summary: Finish creating passkey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyFinishReq'
      responses:
        '200':
          description: The newly registered passkey.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyData'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /passkey/login/start:
    post:
      operationId: passkeyLoginStart
      tags:
        - Passkeys
      summary: Start passkey login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyLoginStartReq'
      responses:
        '200':
          description: WebAuthn credential request options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyStartRsp'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /passkey/login/finish:
    post:
      operationId: passkeyLoginFinish
      tags:
        - Passkeys
      summary: Finish passkey login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyFinishReq'
      responses:
        '200':
          description: The authenticated passkey and user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyLoginFinishRsp'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /passkey/mediation/start:
    post:
      operationId: passkeyMediationStart
      tags:
        - Passkeys
      summary: Start passkey login (Conditional UI)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyLoginStartReq'
      responses:
        '200':
          description: WebAuthn credential request options for conditional UI.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyStartRsp'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /passkey/mediation/finish:
    post:
      operationId: passkeyMediationFinish
      tags:
        - Passkeys
      summary: Finish passkey login (Conditional UI)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyFinishReq'
      responses:
        '200':
          description: The authenticated passkey and user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyLoginFinishRsp'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /passkey/verifySignedData:
    post:
      operationId: passkeyVerifySignedData
      tags:
        - Passkeys
      summary: Verify signed passkey data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyVerifySignedDataReq'
      responses:
        '200':
          description: The verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyVerifySignedDataRsp'
        '400':
          $ref: '#/components/responses/ErrorRsp'
  /users/{userID}/passkeyEvents:
    parameters:
      - $ref: '#/components/parameters/UserID'
    post:
      operationId: passkeyEventCreate
      tags:
        - PasskeyEvents
      summary: Create passkey event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasskeyEventCreateReq'
      responses:
        '200':
          description: The created passkey event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyEvent'
        '400':
          $ref: '#/components/responses/ErrorRsp'
    get:
      operationId: passkeyEventList
      tags:
        - PasskeyEvents
      summary: List passkey events
      responses:
        '200':
          description: A list of passkey events for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyEventList'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /users/{userID}/passkeyEvents/{passkeyEventID}:
    parameters:
      - $ref: '#/components/parameters/UserID'
      - name: passkeyEventID
        in: path
        required: true
        schema:
          type: string
    delete:
      operationId: passkeyEventDelete
      tags:
        - PasskeyEvents
      summary: Delete passkey event
      responses:
        '200':
          description: The passkey event was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericRsp'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /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'
  /exports/{exportType}:
    parameters:
      - name: exportType
        in: path
        required: true
        schema:
          type: string
          enum:
            - users
            - passkeyEvents
    get:
      operationId: exportList
      tags:
        - Exports
      summary: List project exports
      responses:
        '200':
          description: A list of available export files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportList'
        '404':
          $ref: '#/components/responses/ErrorRsp'
  /exports/{exportType}/{filename}/downloadLink:
    parameters:
      - name: exportType
        in: path
        required: true
        schema:
          type: string
      - name: filename
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: exportDownloadLink
      tags:
        - Exports
      summary: Get export download link
      responses:
        '200':
          description: A time-limited download link for the export file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportDownloadLink'
        '404':
          $ref: '#/components/responses/ErrorRsp'
components:
  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.
  parameters:
    UserID:
      name: userID
      in: path
      required: true
      description: The Corbado user ID (e.g. usr-4693224802260150919).
      schema:
        type: string
    Sort:
      name: sort
      in: query
      required: false
      description: Field and direction to sort by, e.g. created:desc.
      schema:
        type: string
    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
    PageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        format: int32
        default: 10
  responses:
    ErrorRsp:
      description: An error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorRsp'
  schemas:
    User:
      type: object
      required:
        - userID
        - status
        - updated
        - updatedMs
      properties:
        userID:
          type: string
          example: usr-4693224802260150919
        status:
          type: string
          enum:
            - pending
            - active
            - disabled
        fullName:
          type: string
          example: Jane Doe
        explicitWebauthnID:
          type: string
        updated:
          type: string
          format: date-time
        updatedMs:
          type: integer
          format: int64
    UserCreateReq:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - pending
            - active
            - disabled
        fullName:
          type: string
        explicitWebauthnID:
          type: string
    UserUpdateReq:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - active
            - disabled
        fullName:
          type: string
    UserList:
      type: object
      required:
        - users
        - paging
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
        paging:
          $ref: '#/components/schemas/Paging'
    Identifier:
      type: object
      required:
        - identifierID
        - userID
        - identifierType
        - identifierValue
        - status
      properties:
        identifierID:
          type: string
          example: emai-2398470283402934
        userID:
          type: string
        identifierType:
          type: string
          enum:
            - email
            - phone
            - username
        identifierValue:
          type: string
          example: jane.doe@example.com
        status:
          type: string
          enum:
            - primary
            - verified
            - pending
        created:
          type: string
          format: date-time
    IdentifierCreateReq:
      type: object
      required:
        - identifierType
        - identifierValue
        - status
      properties:
        identifierType:
          type: string
          enum:
            - email
            - phone
            - username
        identifierValue:
          type: string
        status:
          type: string
          enum:
            - primary
            - verified
            - pending
    IdentifierUpdateReq:
      type: object
      properties:
        status:
          type: string
          enum:
            - primary
            - verified
            - pending
    IdentifierList:
      type: object
      required:
        - identifiers
        - paging
      properties:
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
        paging:
          $ref: '#/components/schemas/Paging'
    Session:
      type: object
      required:
        - sessionID
        - userID
      properties:
        sessionID:
          type: string
        userID:
          type: string
        expiresMs:
          type: integer
          format: int64
        created:
          type: string
          format: date-time
    SessionList:
      type: object
      required:
        - sessions
        - paging
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        paging:
          $ref: '#/components/schemas/Paging'
    PasskeyData:
      type: object
      properties:
        credentialID:
          type: string
        userID:
          type: string
        attestationType:
          type: string
        transports:
          type: array
          items:
            type: string
        backupEligible:
          type: boolean
        backupState:
          type: boolean
        aaguid:
          type: string
        created:
          type: string
          format: date-time
    CredentialList:
      type: object
      required:
        - credentials
      properties:
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/PasskeyData'
    PasskeyAppendStartReq:
      type: object
      required:
        - userID
      properties:
        userID:
          type: string
        clientInformation:
          $ref: '#/components/schemas/ClientInformation'
    PasskeyLoginStartReq:
      type: object
      properties:
        identifierValue:
          type: string
        clientInformation:
          $ref: '#/components/schemas/ClientInformation'
    PasskeyFinishReq:
      type: object
      required:
        - signedChallenge
      properties:
        signedChallenge:
          type: string
          description: The serialized WebAuthn attestation or assertion response from the browser.
        clientInformation:
          $ref: '#/components/schemas/ClientInformation'
    PasskeyStartRsp:
      type: object
      properties:
        challenge:
          type: string
          description: The serialized PublicKeyCredentialCreationOptions or PublicKeyCredentialRequestOptions JSON.
    PasskeyLoginFinishRsp:
      type: object
      properties:
        userID:
          type: string
        passkey:
          $ref: '#/components/schemas/PasskeyData'
    PasskeyVerifySignedDataReq:
      type: object
      required:
        - signedData
      properties:
        userID:
          type: string
        signedData:
          type: string
    PasskeyVerifySignedDataRsp:
      type: object
      properties:
        valid:
          type: boolean
        userID:
          type: string
    PasskeyEvent:
      type: object
      required:
        - passkeyEventID
        - userID
        - passkeyEventType
      properties:
        passkeyEventID:
          type: string
        userID:
          type: string
        passkeyEventType:
          type: string
          enum:
            - login-success
            - login-error
            - registration-success
            - registration-error
            - login-error-untrusted
        created:
          type: string
          format: date-time
    PasskeyEventCreateReq:
      type: object
      required:
        - passkeyEventType
      properties:
        passkeyEventType:
          type: string
          enum:
            - login-success
            - login-error
            - registration-success
            - registration-error
            - login-error-untrusted
        clientInformation:
          $ref: '#/components/schemas/ClientInformation'
    PasskeyEventList:
      type: object
      required:
        - passkeyEvents
      properties:
        passkeyEvents:
          type: array
          items:
            $ref: '#/components/schemas/PasskeyEvent'
    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
    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.
    ConnectTokenUpdateReq:
      type: object
      properties:
        status:
          type: string
    ConnectTokenList:
      type: object
      required:
        - connectTokens
        - paging
      properties:
        connectTokens:
          type: array
          items:
            $ref: '#/components/schemas/ConnectToken'
        paging:
          $ref: '#/components/schemas/Paging'
    ExportList:
      type: object
      required:
        - exports
      properties:
        exports:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
              sizeBytes:
                type: integer
                format: int64
              created:
                type: string
                format: date-time
    ExportDownloadLink:
      type: object
      properties:
        url:
          type: string
          format: uri
        expiresMs:
          type: integer
          format: int64
    ClientInformation:
      type: object
      description: Client/browser context captured for passkey intelligence and risk analysis.
      properties:
        bluetoothAvailable:
          type: boolean
        userAgent:
          type: string
        clientEnvHandle:
          type: string
        javaScriptHighEntropy:
          type: string
    Paging:
      type: object
      properties:
        page:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
        totalItems:
          type: integer
          format: int32
    GenericRsp:
      type: object
      properties:
        httpStatusCode:
          type: integer
          format: int32
        message:
          type: string
        requestData:
          $ref: '#/components/schemas/RequestData'
        runtime:
          type: number
          format: float
    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
    RequestData:
      type: object
      properties:
        requestID:
          type: string
        link:
          type: string