openapi: 3.0.3
info:
  title: TOTP
  description: >-
    Login using time-based one-time passcodes (TOTP), which can be generated by
    authenticator apps like Google Authenticator. This provides passwordless,
    two-factor authentication using a single login method.
  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/totp/authenticate:
    post:
      operationId: authenticateTOTP
      summary: Authenticate TOTP
      description: >-
        Authenticates a user using a TOTP code generated by the user's
        authenticator app. Once the TOTP is validated using the secret created
        upon registration and the TOTP method configuration, user tokens are
        returned.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTotpTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
        '400':
          content:
            application/json:
              examples:
                userNotFound:
                  value:
                    error_code: '400'
                    message: User not found
                  description: User not found
                invalidTOTPToken:
                  value:
                    error_code: '400'
                    message: Invalid TOTP token
                  description: Invalid TOTP token
                sessionNotFound:
                  value:
                    error_code: '400'
                    message: Session not found
                  description: Session not found
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/totp/transaction/start:
    post:
      operationId: startTransactionSigningTOTP
      summary: Start a transaction signing flow with TOTP
      description: >-
        Start a transaction signing flow with TOTP. Receive a challenge to add
        to the authenticator app.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTotpStartRequestDto'
      responses:
        '200':
          description: Backend auth initialized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTotpStartResponseDto'
        '400':
          content:
            application/json:
              examples:
                failedToInitiateTOTPAuthentication:
                  value:
                    error_code: '400'
                    message: Failed to initiate TOTP authentication
                  description: Failed to initiate TOTP authentication
          description: ''
        '403':
          content:
            application/json:
              examples:
                userNotActive:
                  value:
                    error_code: '403'
                    message: User is not active
                  description: User is not active
          description: ''
        '404':
          content:
            application/json:
              examples:
                userNotFound:
                  value:
                    error_code: '404'
                    message: User not found
                  description: User not found
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/totp/transaction/authenticate:
    post:
      operationId: authenticateTransactionSigningTOTP
      summary: Authenticate transaction signing TOTP
      description: >-
        Authenticates a user using a TOTP code generated by the user's
        authenticator app with the challenge received from the transaction
        start. Once the TOTP is validated using the secret created upon
        registration and the TOTP method configuration, user tokens are
        returned.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTotpTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
        '400':
          content:
            application/json:
              examples:
                userNotFound:
                  value:
                    error_code: '400'
                    message: User not found
                  description: User not found
                invalidTOTPToken:
                  value:
                    error_code: '400'
                    message: Invalid TOTP token
                  description: Invalid TOTP token
                sessionNotFound:
                  value:
                    error_code: '400'
                    message: Session not found
                  description: Session not found
          description: ''
      security:
        - ClientAccessToken: []
  /v1/users/me/totp:
    post:
      operationId: registerTotp
      summary: Register TOTP
      description: >-
        Registers a TOTP authenticator for the logged-in user. The response
        contains the secret and other configuration that will be used to
        generate TOTP codes for authentication. The app must provide it to the
        user (such as via QR) so the user can complete the process using their
        authenticator app. <br><br> **Note:** <ul><li>A TOTP authenticator is
        considered registered even if it wasn't added to an authenticator
        app.</li><li>A user can only have a single TOTP authenticator for a
        given application. Attempting to register another will fail, unless your
        request enables override or you first revoke the authenticator that's
        currently registered.</li></ul>
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTotpRegistrationInputDto'
      responses:
        '201':
          description: The TOTP authenticator has been successfully registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTotpRegistrationOutputDto'
      security:
        - UserAccessToken: []
  /v1/users/me/totp/revoke:
    post:
      operationId: revokeTotp
      summary: Revoke my TOTP
      description: Unregisters the TOTP authenticator of the currently logged-in user.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTotpRevokeInputDto'
      responses:
        '204':
          description: Revoked
      security:
        - UserAccessToken: []
  /v1/users/{userId}/totp/revoke:
    post:
      operationId: revokeTotpManagement
      summary: Revoke TOTP
      description: >-
        Unregisters a user's TOTP authenticator. <br><br>**Required
        permissions**: `apps:delete`, `[appId]:delete`, `authenticators:delete`.
      parameters:
        - name: userId
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTotpRevokeInputDto'
      responses:
        '204':
          description: Revoked
      security:
        - ClientAccessToken: []
components:
  schemas:
    ApiTotpTokenRequestDto:
      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:
          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/).
          allOf:
            - $ref: '#/components/schemas/ApiTokenRequestClaims'
        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.
        token:
          type: string
          description: TOTP code to validate
        identifier_type:
          type: string
          enum:
            - email
            - phone_number
            - user_id
            - username
          description: Type of user identifier used for validating the TOTP
          default: email
        identifier:
          type: string
          description: Identifier of the user that the TOTP was generated for
      required:
        - token
        - identifier
    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
    ApiTotpStartRequestDto:
      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:
          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/).
          allOf:
            - $ref: '#/components/schemas/ApiTokenRequestClaims'
        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.
        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.
        identifier_type:
          type: string
          enum:
            - email
            - phone_number
            - user_id
            - username
          description: Type of user identifier used for login
        identifier:
          type: string
          description: >-
            User identifier, which may correspond to the user's email, phone
            number, username, or user ID. The type of identifier should be
            specified as the `identifier_type`.
      required:
        - approval_data
        - identifier_type
        - identifier
    ApiTotpStartResponseDto:
      type: object
      properties:
        approval_data:
          type: object
          readOnly: true
          example:
            transaction_id: eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT
            sum: '200'
          description: Approval data object.
        challenge:
          type: string
          readOnly: true
          example: '123456'
          description: Totp transaction challenge
      required:
        - approval_data
        - challenge
    ApiTokenRequestClaims:
      type: object
      properties:
        id_token:
          type: object
        access_token:
          type: object
    ClientAttributes:
      type: object
      properties:
        user_agent:
          type: string
        ip_address:
          type: string
    ApiTotpRegistrationInputDto:
      type: object
      properties:
        label:
          type: string
          description: >-
            Account name displayed in the authenticator app. If unspecified, the
            user's email, username, or phone number will be used (ordered by
            preference).
          example: John Doe
        allow_override:
          type: boolean
          description: If `true`, overrides the TOTP secret if one already exists
          default: false
    ApiTotpRegistrationOutputDto:
      type: object
      properties:
        secret:
          type: string
          description: >-
            The secret key used to generate the TOTP code. It can be provided to
            the user to enter manually into the authenticator app.
          readOnly: true
        uri:
          type: string
          description: >-
            A URI containing the secret and other configuration used to generate
            the TOTP code. It can be encoded in a QR code for the user to scan
            using their authenticator app
      required:
        - secret
        - uri
    ApiTotpRevokeInputDto:
      type: object
      properties:
        authenticator_id:
          type: string
          description: Authenticator ID to revoke
  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.
