openapi: 3.0.3
info:
  title: WebAuthn
  description: >-
    Login users using WebAuthn biometrics integrated into your native login
    experience. Although WebAuthn authentication and registration is initiated
    in the frontend, the flows are completed using a backend-to-backend
    integration. The client-side integration can also be implemented using the
    Transmit Platform SDK.
  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/authenticate/start:
    post:
      operationId: authenticationStart
      summary: Start authentication
      security: []
      description: >-
        Start a new webauthn authentication. If successful, the response will
        contain a `credential_request_options` field that should be passed in
        the WebAuthn `navigator.credentials.get()` API call. Note that 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/ApiWebAuthnAuthenticateStartRequestDto'
      responses:
        '200':
          description: Authentication options
          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: ''
        '401':
          content:
            application/json:
              examples:
                NoCredentialsRegistered:
                  value:
                    error_code: no_credentials_registered
                    message: Invalid credentials
                  description: >-
                    When a username input provided but there are no credentials
                    for the user
          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/authenticate:
    post:
      operationId: authenticateWebauthnCredential
      summary: Authenticate WebAuthn
      description: >-
        Authenticate a user using their WebAuthn credentials. Retrieves tokens
        based on a the encoded result of the webauthn authentication.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiWebauthnTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
        '400':
          content:
            application/json:
              examples:
                invalidRequest:
                  value:
                    error_code: webauthn_encoded_result
                    message: Invalid webauthn encoded result
                  description: Invalid webauthn encoded result
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/webauthn/external/register/hosted/hint:
    post:
      operationId: hosted-webauthn-registration-hint
      summary: Init hosted registration
      description: >-
        Initializes a hosted WebAuthn registration flow for a logged-out user
        (see [Quickstart](/guides/user/auth_webauthn_registr_quickstart/)). This
        API is used to securely set the WebAuthn username in the backend, and
        returns a registration token used to start the registration flow.
        **Relevant only for hosted login scenarios**
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebauthnExternalRegisterHintRequestDto'
      responses:
        '200':
          description: Registered credential details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebauthnExternalRegisterHintResponseDto'
        '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: ''
      security:
        - ClientAccessToken: []
  /v1/auth/webauthn/register/start:
    post:
      operationId: webauthn-registration-start
      summary: Start registration
      description: >-
        Starts a registration of WebAuthn credentials for a specified user,
        returning a challenge to be signed by the client. If successful, the
        response will contain a `credential_creation_options` field that should
        be passed in the WebAuthn `navigator.credentials.create()` API call.
        Note that 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/WebauthnRegisterStartRequestDto'
      responses:
        '200':
          description: Active WebAuthn session info
          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:
                ClientNotFound:
                  value:
                    error_code: client_not_found
                    message: Client not found
          description: ''
  /v1/auth/webauthn/register:
    post:
      operationId: webauthn-registration
      summary: Register for logged-in user
      description: >-
        Complete WebAuthn credential registration for a user that is currently
        logged in using a different Transmit authentication method. This API
        must be called from the backend using the user access token returned
        upon successful authentication. If successful, the credential will be
        registered for the user that corresponds to the authorization token.
      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/WebauthnRegisterCompleteResponseDto'
        '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: ''
      security:
        - UserAccessToken: []
  /v1/auth/webauthn/external/register:
    post:
      operationId: webauthn-registration-external
      summary: Register for logged-out user
      description: >-
        Complete WebAuthn credential registration for a new user (in Transmit)
        or a user that isn't currently logged in via Transmit. This API must be
        called from the backend using a client access token. If successful, the
        credentials will be registered for the user corresponding to the
        external user ID in the request. If no user is found, a new user will be
        created.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebauthnRegisterCompleteExternalRequestDto'
      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: ''
        '404':
          content:
            application/json:
              examples:
                ClientNotFound:
                  value:
                    error_code: client_not_found
                    message: Client not found
          description: ''
      security:
        - ClientAccessToken: []
components:
  schemas:
    ApiWebauthnTokenRequestDto:
      type: object
      properties:
        resource:
          type: string
          description: >-
            Resource URI the authentication request is attempting to access,
            which is reflected in the audience (`aud` claim) of the access
            token. This must be configured as resource for the application.
        claims:
          type: object
          example:
            id_token:
              roles: null
          description: >-
            Used to request additional claims in the ID token, such as roles,
            permissions, and other user profile data. The structure is per the
            [OIDC
            Standard](https://openid.net/specs/openid-connect-core-1_0-final.html#ClaimsParameter).
            For supported claims and how to request custom claims, see the [ID
            Token
            Reference](https://developer.transmitsecurity.com/openapi/id_token_reference/).
        org_id:
          type: string
          description: Organization ID, used for member login in B2B scenarios
        client_attributes:
          description: Client attributes
          allOf:
            - $ref: '#/components/schemas/ClientAttributes'
        session_id:
          type: string
          description: >-
            Used to associate the authentication with an existing session (such
            as for MFA). If unspecified, a new session is created and the
            session ID is returned.
        webauthn_encoded_result:
          type: string
          description: WebAuthn assertion data (base64 encoded)
      required:
        - webauthn_encoded_result
    ApiTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: >-
            User access token for accessing endpoints on behalf of the
            authenticated user.
        id_token:
          type: string
          description: ID token that identifies the user.
        refresh_token:
          type: string
          description: Refresh token used to refresh an expired access token.
        token_type:
          type: string
          description: Bearer.
        expires_in:
          type: number
          description: Expiration time of the access token in seconds.
          default: 3600
        session_id:
          type: string
          description: ID of the session in which the authentication occurs.
      required:
        - access_token
        - token_type
        - expires_in
        - session_id
    ClientAttributes:
      type: object
      properties:
        user_agent:
          type: string
        ip_address:
          type: string
    WebauthnRegisterCompleteExternalRequestDto:
      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.
        external_user_id:
          type: string
          description: >-
            A unique identifier in the tenant, which corresponds to an
            identifier of the user in your system.
        user_email:
          type: string
          description: The user's primary email address
      required:
        - webauthn_encoded_result
        - external_user_id
    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
    WebauthnExternalRegisterHintRequestDto:
      type: object
      properties:
        webauthn_identifier:
          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.
          maxLength: 64
          minLength: 1
        webauthn_display_name:
          type: string
          description: >-
            Human-palatable name for the user account, only for display (max 64
            characters).  If not set, the username parameter will also act as
            the display name
          maxLength: 64
          minLength: 1
        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
        redirect_uri:
          type: string
          description: URI to redirect to upon completing the registration process
      required:
        - webauthn_identifier
        - redirect_uri
    WebauthnExternalRegisterHintResponseDto:
      type: object
      properties:
        register_webauthn_cred_token:
          type: string
          description: >-
            Token returned to relying party to ensure the specified username is
            being used for webauthn credential registration
      required:
        - register_webauthn_cred_token
    WebauthnRegisterStartRequestDto:
      type: object
      properties:
        client_id:
          type: string
          description: Your client ID.
        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.
          maxLength: 64
          minLength: 1
        display_name:
          type: string
          description: >-
            Human-palatable name for the user account, only for display (max 64
            characters).  If not set, the username parameter will also act as
            the display name
          maxLength: 64
          minLength: 1
        timeout:
          type: number
          description: |-
            The timeout in seconds for the registration modal. 
                Must be between 30 and 600. 
                Default is 300 seconds.
        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:
        - client_id
        - username
    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
    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
    WebauthnRegisterCompleteResponseDto:
      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
      required:
        - webauthn_session_id
        - webauthn_username
        - credential_id
        - authenticator_attachment
    ApiWebAuthnAuthenticateStartRequestDto:
      type: object
      properties:
        client_id:
          type: string
          description: >-
            The client ID of the application the user is trying to authenticate
            to.
        timeout:
          type: number
          description: |-
            The timeout in seconds for the authentication modal. 
                Must be between 30 and 600. 
                Default is 300 seconds.
        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
          maxLength: 64
          minLength: 1
        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
    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
    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
    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
    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
    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
    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
  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.
