openapi: 3.0.3
info:
  title: WebAuthn Cross-Device
  description: >-
    APIs to manage cross-device flow for WebAuthn registration and
    authentication.
  version: ''
servers:
  - url: https://api.sbx.transmitsecurity.io/cis
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/cis
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/cis
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/cis
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/cis
    description: Production environment (AU)
security: []
paths:
  /v1/auth/webauthn/cross-device/register/start:
    post:
      operationId: webauthn-cross-device-registration-start
      summary: Start registration
      description: >-
        Starts a WebAuthn registration process on a secondary device, and
        returns a challenge for the client to sign. If successful, the response
        will contain a `credential_creation_options` field that should be passed
        in the WebAuthn `navigator.credentials.create()` API call.
        <br><br>**Note:** Some fields (`user.id` and `challenge`) in the
        `credential_creation_options` object are base64 encoded and must first
        be decoded and converted to an array buffer. It is recommended to use
        the [webauthn-json](https://github.com/github/webauthn-json) library
        that handles this.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCrossDeviceRegisterStartRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebauthnRegisterStartResponseDto'
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                CrossDeviceTicketNotFound:
                  value:
                    error_code: cross_device_ticket_not_found
                    message: Cross device ticket not found
                  description: When the ticketId doesn't exist
          description: ''
  /v1/auth/webauthn/cross-device/register/init:
    post:
      operationId: webauthn-cross-device-registration-init
      summary: Init logged-in registration
      description: >-
        Initializes a flow that will register WebAuthn credentials using a
        secondary device. Requested by the access device (e.g., desktop) and
        requires a logged-in user. Returns `cross_device_ticket_id`, which
        should be passed to the biometric device to start the device
        registration, such as by encoding it in a QR code.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCrossDeviceRegisterInitRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCrossDeviceInitResponseDto'
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                ClientNotFound:
                  value:
                    error_code: client_not_found
                    message: Client not found
                  description: When the clientId doesn't exist
          description: ''
      security:
        - UserAccessToken: []
  /v1/auth/webauthn/cross-device/external/register/init:
    post:
      operationId: webauthn-cross-device-external-registration-init
      summary: Init logged-out registration
      description: >-
        Initializes a flow that will register WebAuthn credentials using a
        secondary device. Requested by the access device (e.g., desktop) for a
        user that isn't logged in via Transmit (e.g., after password login via
        an external identity provider). Returns `cross_device_ticket_id`, which
        should be passed to the biometric device to start the device
        registration, such as by encoding it in a QR code. <br><br>**Required
        permissions**: `apps:execute`, `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/ApiCrossDeviceExternalRegisterInitRequestDto
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCrossDeviceInitResponseDto'
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                ClientNotFound:
                  value:
                    error_code: client_not_found
                    message: Client not found
                  description: When the clientId doesn't exist
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/webauthn/cross-device/register:
    post:
      operationId: webauthn-cross-device-registration
      summary: Complete registration
      description: >-
        Completes WebAuthn credential registration for the user on a secondary
        device. For a logged-in registration flow, the user is derived from the
        access token. For a logged-out registration flow, the user corresponds
        to the requested external user ID. If no user is found, a new user will
        be created. <br><br>**Required permissions**: `apps:execute`,
        `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebauthnRegisterCompleteRequestDto'
      responses:
        '200':
          description: Registered credential details
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/WebauthnRegisterCompleteExternalResponseDto
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/webauthn/cross-device/abort:
    post:
      operationId: webauthn-cross-device-abort
      summary: Abort cross-device flow
      description: >-
        Terminates the cross-device flow from the auth device, and updates the
        status to `aborted`. <br><br>**Required permissions**: `apps:execute`,
        `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCrossDeviceTicketIdRequestDto'
      responses:
        '204':
          description: ''
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                CrossDeviceTicketNotFound:
                  value:
                    error_code: cross_device_ticket_not_found
                    message: Cross device ticket not found
                  description: When the ticketId doesn't exist
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/webauthn/cross-device/status:
    get:
      operationId: webauthn-cross-device-status
      summary: Get cross-device status
      description: >-
        Checks the status of a cross-device flow. This is used by the access
        device.
      parameters:
        - name: cross_device_ticket_id
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiWebauthnCrossDeviceStatusResponse'
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                CrossDeviceTicketNotFound:
                  value:
                    error_code: cross_device_ticket_not_found
                    message: Cross device ticket not found
                  description: When the ticketId doesn't exist
          description: ''
  /v1/auth/webauthn/cross-device/attach-device:
    post:
      operationId: webauthn-cross-device-attach-device
      summary: Attach device
      description: >-
        Indicates that the auth device has engaged in the flow, such as when the
        user scans a QR encoding the cross-device ticket ID. This updates the
        flow status to `scanned`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCrossDeviceTicketIdRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCrossDeviceAttachDeviceResponseDto'
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                CrossDeviceTicketNotFound:
                  value:
                    error_code: cross_device_ticket_not_found
                    message: Cross device ticket not found
                  description: When the ticketId doesn't exist
          description: ''
  /v1/auth/webauthn/cross-device/authenticate/init:
    post:
      operationId: webauthn-cross-device-authentication-init
      summary: Init authentication
      description: >-
        Initializes a flow that will authenticate WebAuthn credentials using a
        secondary device. Requested by the access device (e.g., desktop) before
        delegating authentication to another device. Returns a cross-device
        ticket ID that should be passed to the biometric device to start the
        authentication (e.g., by encoding it in a QR code).
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCrossDeviceAuthenticateInitRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCrossDeviceInitResponseDto'
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                ClientNotFound:
                  value:
                    error_code: client_not_found
                    message: Client not found
                  description: When the clientId doesn't exist
          description: ''
  /v1/auth/webauthn/cross-device/authenticate/start:
    post:
      operationId: webauthn-cross-device-authenticate-start
      summary: Start authentication
      description: >-
        Start a WebAuthn authentication process using a secondary device. If
        successful, the response will contain a `credential_request_options`
        field that should be passed in the WebAuthn
        `navigator.credentials.get()` API call. <br><br>**Note:** Some fields
        (`challenge` and each `id` in the `allowCredentials` list) in the
        `credential_request_options` object are base64 encoded and must first be
        decoded and converted to array buffer. It is recommended to use the
        [webauthn-json](https://github.com/github/webauthn-json) library that
        handles this.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCrossDeviceAuthenticateStartRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiWebAuthnAuthenticateStartResponse'
        '400':
          content:
            application/json:
              examples:
                InvalidRequest:
                  value:
                    error_code: invalid_request
                    message: 'Invalid request: property should not be null or undefined'
          description: ''
        '404':
          content:
            application/json:
              examples:
                CrossDeviceTicketNotFound:
                  value:
                    error_code: cross_device_ticket_not_found
                    message: Cross device ticket not found
                  description: When the ticketId doesn't exist
          description: ''
components:
  schemas:
    ApiCrossDeviceExternalRegisterInitRequestDto:
      type: object
      properties:
        external_user_id:
          type: string
          description: >-
            A unique identifier in the tenant, which corresponds to an
            identifier of the user in your system.
          maxLength: 64
          minLength: 1
        username:
          type: string
          description: >-
            Account name for this Relying Party. This is used both for display
            purposes, as well as during recovery flows where the user is asked
            for the account name.
      required:
        - external_user_id
        - username
    ApiCrossDeviceInitResponseDto:
      type: object
      properties:
        cross_device_ticket_id:
          type: string
          description: >-
            Identifies the cross-device flow. Required for starting the flow on
            the secondary device.
      required:
        - cross_device_ticket_id
    WebauthnRegisterCompleteRequestDto:
      type: object
      properties:
        webauthn_encoded_result:
          type: string
          description: >-
            WebAuthn attestation data returned by the browser upon credential
            creation, which must be converted from array buffer to a base64
            string. If [webauthn-json](https://github.com/github/webauthn-json)
            `create()` was used, this is already taken care of.
      required:
        - webauthn_encoded_result
    WebauthnRegisterCompleteExternalResponseDto:
      type: object
      properties:
        webauthn_session_id:
          type: string
          description: WebAuthn session identifier
        user_id:
          type: string
          description: Transmit user ID, autogenerated upon user creation
        webauthn_username:
          type: string
          description: Name of user account, as specified in the WebAuthn registration
        credential_id:
          type: string
          description: WebAuthn credential ID
        authenticator_attachment:
          type: string
          enum:
            - platform
            - cross-platform
          description: >-
            The authenticators' attachment modalities. Cross-platform
            authenticator are external to the current device, such as a USB
            security key or a different device
        aaguid:
          type: string
          description: The authenticator's AAGUID
        external_user_id:
          type: string
          description: External User identifier
        is_user_created:
          type: boolean
          description: Indicates if this is a new user or not
      required:
        - webauthn_session_id
        - webauthn_username
        - credential_id
        - authenticator_attachment
        - external_user_id
        - is_user_created
    ApiCrossDeviceTicketIdRequestDto:
      type: object
      properties:
        cross_device_ticket_id:
          type: string
          description: Webauthn cross device ticket ID
      required:
        - cross_device_ticket_id
    ApiCrossDeviceRegisterInitRequestDto:
      type: object
      properties:
        username:
          type: string
          description: >-
            Account name for this Relying Party. This is used both for display
            purposes, as well as during recovery flows where the user is asked
            for the account name.
        limit_single_credential_to_device:
          type: boolean
          description: >-
            Set to True in order to limit the creation of multiple credentials
            for the same account on a single authenticator. Default is False.
          default: false
      required:
        - username
    ApiWebauthnCrossDeviceStatusResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/WebauthnCrossDeviceStatus'
        session_id:
          type: string
          description: session id return on cross device authentication success
      required:
        - status
        - session_id
    ApiCrossDeviceAttachDeviceResponseDto:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/WebauthnCrossDeviceStatus'
        started_at:
          type: string
        approval_data:
          type: object
          example:
            transaction_id: eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT
            sum: '200'
          description: >-
            Flat object that contains the data that your customer should approve
            for a transaction signing or custom approval flow. It can contain up
            to 10 keys, and only alphanumeric characters, underscores, hyphens,
            and periods. It will be returned as a claim in the ID token upon
            successful authentication.
      required:
        - status
    ApiCrossDeviceAuthenticateInitRequestDto:
      type: object
      properties:
        client_id:
          type: string
          description: >-
            The client ID of the application the user is trying to authenticate
            to.
        username:
          type: string
          description: >-
            Name of user account, as used in the WebAuthn registration. If not
            provided, the authentication will start without the context of a
            user and it will be inferred by the chosen passkey
        approval_data:
          type: object
          example:
            transaction_id: eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT
            sum: '200'
          description: >-
            Flat object that contains the data that your customer should approve
            for a transaction signing or custom approval flow. It can contain up
            to 10 keys, and only alphanumeric characters, underscores, hyphens,
            and periods. It will be returned as a claim in the ID token upon
            successful authentication.
      required:
        - client_id
    ApiCrossDeviceAuthenticateStartRequestDto:
      type: object
      properties:
        cross_device_ticket_id:
          type: string
          description: Returned upon initializing the authentication flow
      required:
        - cross_device_ticket_id
    ApiWebAuthnAuthenticateStartResponse:
      type: object
      properties:
        webauthn_session_id:
          type: string
          description: WebAuthn session identifier
        credential_request_options:
          $ref: '#/components/schemas/WebAuthnAuthenticationOptions'
      required:
        - webauthn_session_id
        - credential_request_options
    ApiCrossDeviceRegisterStartRequestDto:
      type: object
      properties:
        cross_device_ticket_id:
          type: string
          description: >-
            cross device ticket id returned from the init cross device
            registration API
      required:
        - cross_device_ticket_id
    WebauthnRegisterStartResponseDto:
      type: object
      properties:
        webauthn_session_id:
          type: string
          description: WebAuthn session identifier
        credential_creation_options:
          $ref: '#/components/schemas/WebauthnRegistrationOptions'
      required:
        - webauthn_session_id
        - credential_creation_options
    WebauthnCrossDeviceStatus:
      type: string
      enum:
        - pending
        - scanned
        - success
        - error
        - timeout
        - aborted
    WebAuthnAuthenticationOptions:
      type: object
      properties:
        allowCredentials:
          type: array
          items:
            $ref: '#/components/schemas/AuthenticationOptionsAllowedCredential'
        rawChallenge:
          type: string
          description: >-
            Represents the natural WebAuthn challenge. Will Only be present in
            approval flows
        challenge:
          type: string
        timeout:
          type: number
        rpId:
          type: string
          description: >-
            Relying Party ID. Must be a valid domain pre-configured in the Admin
            Portal for the application
          pattern: /^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\.[a-zA-Z]{2,}$/
        attestation:
          type: string
          enum:
            - none
          example: none
          default: none
        userVerification:
          type: string
          enum:
            - preferred
            - required
          default: preferred
          example: preferred
        extensions:
          type: object
      required:
        - allowCredentials
        - challenge
        - rpId
    WebauthnRegistrationOptions:
      type: object
      properties:
        attestation:
          type: string
          enum:
            - none
          default: none
        authenticatorSelection:
          $ref: '#/components/schemas/ApiAuthenticatorSelectionCriteria'
        extensions:
          $ref: '#/components/schemas/ApiAuthenticationExtensionsClientInputs'
        excludeCredentials:
          type: array
          items:
            type: string
        pubKeyCredParams:
          type: array
          items:
            $ref: '#/components/schemas/ApiPublicKeyCredentialParameters'
        timeout:
          type: number
        challenge:
          type: string
        user:
          $ref: '#/components/schemas/ApiRegistrationOptionsUser'
        rp:
          $ref: '#/components/schemas/ApiRegistrationOptionsRp'
      required:
        - pubKeyCredParams
        - challenge
        - user
        - rp
    ApiAuthenticatorSelectionCriteria:
      type: object
      properties:
        authenticatorAttachment:
          type: string
          enum:
            - platform
            - cross-platform
          description: >-
            The authenticators' attachment modalities. Cross-platform
            authenticator are external to the current device, such as a USB
            security key or a different device
          default: platform
        requireResidentKey:
          type: boolean
        residentKey:
          type: object
        userVerification:
          type: string
          enum:
            - preferred
            - required
          default: preferred
    ApiAuthenticationExtensionsClientInputs:
      type: object
      properties:
        appid:
          type: string
        credProps:
          type: boolean
        hmacCreateSecret:
          type: boolean
    ApiRegistrationOptionsUser:
      type: object
      properties:
        id:
          type: string
          description: User handle
        name:
          type: string
          description: The webauthn username
        displayName:
          type: string
          description: The user display name
      required:
        - id
        - name
        - displayName
    ApiRegistrationOptionsRp:
      type: object
      properties:
        id:
          type: string
          description: >-
            Relying Party ID. Must be a valid domain pre-configured in the Admin
            Portal for the application
          pattern: /^[a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\.[a-zA-Z]{2,}$/
        name:
          type: string
          description: Relying party displayable name
        icon:
          type: string
      required:
        - id
        - name
        - icon
    AuthenticationOptionsAllowedCredential:
      type: object
      properties:
        type:
          type: string
          description: Key type. Should always be `public-key`
          enum:
            - public-key
          default: public-key
          example: public-key
        id:
          type: string
          description: The credential ID
        transports:
          type: array
          default:
            - internal
          example:
            - internal
          items:
            type: string
            enum:
              - internal
      required:
        - type
        - id
        - transports
    ApiPublicKeyCredentialParameters:
      type: object
      properties:
        alg:
          type: number
        type:
          type: string
          example: public-key
          default: public-key
          enum:
            - public-key
          description: Key type. Should always be `public-key`
      required:
        - alg
        - type
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    UserAccessToken:
      type: http
      description: >-
        A token returned upon end-user authentication, which provides access to
        resources and data for the user and app for which it was generated
      scheme: bearer
      bearerFormat: JWT
    AdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by a management application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to all resources for the tenant and its apps
    ClientAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by an end-user application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to resources and data on the tenant level or associated with the
        specific application (but not other apps in the tenant)
    OrgAdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token returned upon B2B authentication for a user that has the
        organizationAdmin or organizationCreator role.
