openapi: 3.0.3
info:
  title: WebAuthn Hosted
  description: >-
    Log in users using WebAuthn biometrics and a hosted login experience. This
    implements a frontend integration for authentication, where the client
    obtains an authorization code that your app can exchange in the backend for
    user tokens.
  version: ''
servers:
  - url: https://api.transmitsecurity.io/cis
    description: Production environment (US, worldwide, except EU)
  - url: https://api.eu.transmitsecurity.io/cis
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/cis
    description: Production environment (CA)
security: []
paths:
  /v1/auth/webauthn:
    get:
      operationId: startBindIdAuth
      summary: Login with WebAuthn Hosted
      description: >-
        Authenticate the user using secured biometrics. This endpoint should be
        called from the user's browser. It will redirect the User Agent to the
        login page and redirect back to Transmit upon successful authentication.
        Once Transmit verifies the authentication response, the User Agent will
        be redirected to the redirect_uri specified in the request. This URI
        will now include a code parameter in the query, which will be later
        exchanged for a token via the /token endpoint.
      parameters:
        - name: client_id
          required: true
          in: query
          description: >-
            Client ID of the application requesting authentication, retrieved
            from the Transmit Admin Portal
          example: DgsdfhSDsdfhtSDFXCCXBVMKPws345yscv2345XCZV
          schema:
            maxLength: 150
            type: string
        - name: redirect_uri
          required: true
          in: query
          example: https://www.example.com/login
          description: >-
            URI to redirect to upon completion of the IDP flow. This is the
            server GET endpoint used to call the token endpoint, and should
            accept "code" as a query parameter. This URI must also be configured
            as an allowed redirect URI in the Transmit Admin Portal
          schema:
            type: string
        - name: create_new_user
          required: false
          in: query
          example: false
          description: >-
            Indicates if a new user should be created if no user with associated
            email was found. If enabled, public signups must also be configured
            as allowed for the application.
          schema:
            default: true
            type: boolean
        - name: resource
          required: false
          in: query
          description: Resource URI the login is attempting to access.
          schema:
            type: string
        - name: require_mfa
          required: false
          in: query
          example: true
          description: Require multi factor authentication for this authentication request.
          schema:
            default: false
            type: boolean
        - name: login_hint
          required: false
          in: query
          example: user@acme.com
          description: Hint for the user's login identifier.
          schema:
            type: string
        - name: custom_message
          required: false
          in: query
          example: Welcome to Acme
          description: >-
            Custom message to present on the consent screens, which provides
            authentication context details.
          schema:
            type: string
        - name: verifications
          required: false
          in: query
          description: >-
            List of data verifications to try and execute, specified as a
            space-delimited string. Email address will be verified by default,
            but this can be used to request a verified phone number (`phone`).
            If the data is already verified, it won't be verified again. The
            `acr` claim of the resulting ID token will indicate which data is
            verified.
          example: phone
          schema:
            type: string
        - name: ui_locales
          required: false
          in: query
          description: >-
            Preferred languages for the user interface, specified as a
            space-separated list of language tag values [RFC5646], ordered by
            preference.
          schema:
            type: string
        - name: claims
          required: false
          in: query
          example: '{"id_token":{"roles":null}}'
          description: >-
            A stringified object 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/).

            **Note**: You should stringify the value.
          schema:
            type: string
        - name: state
          required: false
          in: query
          description: >-
            An opaque string that is used to maintain state between the request
            and the callback. It will be added to the redirect URI as a query
            parameter, which should be validated by your server to protect
            against cross-site request forgery (CSRF) attacks
          schema:
            type: string
        - name: nonce
          required: false
          in: query
          description: >-
            A random value that is included in the authentication request from
            the client (e.g. browser) to mitigate replay attacks. It will be
            added to the id_token and the backend service should only accept
            id_tokens that include the same nonce value as the one included in
            the original request
          schema:
            type: string
        - name: org_id
          required: false
          in: query
          description: Organization ID, used for member login in B2B scenarios
          schema:
            type: string
      responses:
        '302':
          description: Redirect with code
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRedirectUriHttpError'
  /v1/token:
    post:
      operationId: tokenExchange
      summary: Exchange code for token
      description: >-
        Retrieve ID and access tokens. This API is used to retrieve ID and
        access tokens using the code that was returned in the redirect URI as a
        query parameter (for example, when the user clicks a magic link). It may
        also create a new user if create_new_user was set to true in the send
        request and no user exists for the email address or phone number
        (depending on the flow).
      deprecated: true
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiTokenExchangeRequestInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenExchangeResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
  /v1/auth/logout:
    post:
      operationId: logout
      summary: Logout
      description: >-
        Logout the user from a specific session. The user and session are
        derived from the access token used to authorize the request (which was
        issued based on the authentication that created the session)
      parameters: []
      responses:
        '200':
          description: Sessions deleted Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiLogoutResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTokenHttpError'
      security:
        - bearer: []
components:
  schemas:
    ApiLogoutResponse:
      type: object
      properties:
        sessions_count:
          type: number
          description: Number of logged out sessions
      required:
        - sessions_count
    BadRequestException:
      type: object
      properties: {}
    InvalidTokenHttpError:
      type: object
      properties:
        message:
          type: string
          example: Invalid token
        error_code:
          type: number
          example: 401
      required:
        - message
        - error_code
    ApiTokenExchangeRequestInput:
      type: object
      properties:
        code:
          type: string
          description: >-
            Authorization code returned in the redirect URI as a query parameter
            upon successful authentication
          example: GZxLFKTDCnlANVTxNvaWz7AIGPpXqZYSXdAwjiWRuOH
        client_id:
          type: string
          description: Client ID of the application requesting the token
          example: DgsdfhSDsdfhtSDFXCCXBVMKPws345yscv2345XCZV
          maxLength: 50
        client_secret:
          type: string
          description: Client Secret of the application requesting the token
          example: FzxvdDMbvxnc45sdfb789XCVGEW6usazxcvbw3KPsb23
          maxLength: 50
      required:
        - code
        - client_id
        - client_secret
    ApiTokenExchangeResponse:
      type: object
      properties:
        id_token:
          type: string
        access_token:
          type: string
        refresh_token:
          type: string
        is_user_created:
          type: boolean
          description: Indicates if this is a new user or not
      required:
        - id_token
        - access_token
        - refresh_token
        - is_user_created
    BadRequestHttpError:
      type: object
      properties:
        message:
          example: Bad request
          type: array
          items:
            type: string
        error_code:
          type: number
          example: 400
      required:
        - message
        - error_code
    InvalidRedirectUriHttpError:
      type: object
      properties:
        message:
          type: string
          example: Invalid redirect_uri
        error_code:
          type: number
          example: 400
      required:
        - message
        - error_code
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
