openapi: 3.0.3
info:
  title: Passwords
  description: >-
    Login users using passwords. This implements a backend-to-backend
    integration for password 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/password/authenticate:
    post:
      operationId: authenticatePassword
      summary: Authenticate password
      description: >-
        Authenticates a user using their username and password. The value of
        this username may correspond to the user's username, phone number, or
        email (based on what was used to register their password credentials,
        see [Register
        password](/openapi/user/user.openapi/other/addpasswordcredentialstocurrentuser)).
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiPasswordTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
        '400':
          content:
            application/json:
              examples:
                sessionNotFound:
                  value:
                    error_code: '400'
                    message: Session not found
                  description: Session not found
          description: ''
        '401':
          content:
            application/json:
              examples:
                invalidRequest:
                  value:
                    error_code: '401'
                    message: Invalid username or password
                  description: Invalid username or password
          description: ''
        '403':
          content:
            application/json:
              examples:
                invalidRequest:
                  value:
                    error_code: '403'
                    message: User suspended from authenticating using password
                  description: User suspended from authenticating using password
                userNotActive:
                  value:
                    error_code: '403'
                    message: User not active
                  description: User not active
                loginPreferencesNotConfigured:
                  value:
                    error_code: '403'
                    message: >-
                      Password authentication method is not configured or
                      disabled for this application
                  description: >-
                    Password authentication method is not configured or disabled
                    for this application
          description: ''
      security:
        - ClientAccessToken: []
components:
  schemas:
    ApiPasswordTokenRequestDto:
      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.
        username:
          type: string
          description: >-
            Identifier of the user, which may contain the user's username, email
            or phone number (depending on what was used to register password
            credentials). The `username_type` must match the type of identifier
            used.
        password:
          type: string
          description: Password
        username_type:
          type: string
          enum:
            - username
            - email
            - phone_number
          description: Type of user identifier used to register the password
          default: username
      required:
        - username
        - password
    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
    ApiTokenRequestClaims:
      type: object
      properties:
        id_token:
          type: object
        access_token:
          type: object
    ClientAttributes:
      type: object
      properties:
        user_agent:
          type: string
        ip_address:
          type: string
  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.
