openapi: 3.0.3
info:
  title: Passwords
  description: >-
    Login users using passwords. This implements a frontend integration for
    password authentication, where passwords are handled only by the client. If
    the password credentials are valid, the client can obtain an authorization
    code that your app can exchange in the backend for user tokens.
  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/login:
    post:
      operationId: login
      summary: Login with password
      description: Authenticate a user with a password
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiPasswordLoginInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-login
                type: object
                required:
                  - result
                description: The URL to start the authorization flow
                properties:
                  result:
                    $ref: '#/components/schemas/ApiPasswordLoginResponse'
        '401':
          description: When the  username/email and password don't match or don't exist
        '403':
          description: When the user has to change the password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResetPasswordRequiredErrorResponse'
  /v1/auth/password/reset/email/link:
    post:
      operationId: sendForgotPasswordEmail
      summary: Start reset by email link
      description: >-
        Starts a password reset flow by sending an email magic link. Once
        clicked, the User Agent will be redirected to the URI specified in this
        request. This URI will include a code required to reset the password.
        <br><br>**Required permissions**: `apps:execute`, `[appId]:execute`,
        `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSendResetPasswordEmailLinkInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSendResetPasswordEmailResponse'
        '403':
          description: When the email of the user is not verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
        '404':
          description: >-
            When there is no user with the requested email as a primary email in
            the tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/auth/password/reset/link:
    post:
      operationId: generateResetPasswordLink
      summary: Generate reset link
      description: >-
        Starts a password reset flow by generating a magic link. Once clicked,
        the User Agent will be redirected to the URI specified in this request.
        This URI will include a code required to reset the password.
        <br><br>**Required permissions**: `apps:execute`, `[appId]:execute`,
        `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiGenerateResetPasswordLinkInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGenerateResetPasswordLinkResponse'
        '404':
          description: >-
            When there is no user with the requested email as a primary email in
            the tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/auth/password/reset/email/otp:
    post:
      operationId: sendResetPasswordEmailOTP
      summary: Start reset by Email OTP
      description: >-
        Starts a password reset flow by sending an Email OTP. <br><br>**Required
        permissions**: `apps:execute`, `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSendResetPasswordEmailOtpInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSendResetPasswordEmailOtpResponse'
        '403':
          description: >-
            When the email of the user is not verified, a forbidden error will
            be returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
        '404':
          description: >-
            When there is no user with the requested email address as primary
            email address in the tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/auth/password/reset/email/otp/validate:
    post:
      operationId: validateResetPasswordEmailOTP
      summary: Validate reset OTP Email
      description: >-
        Validate a reset password OTP. <br><br>**Required permissions**:
        `apps:execute`, `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiVerifyResetEmailOtpInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidateResetPasswordResponse'
        '403':
          description: When the provided OTP is expired or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
        '404':
          description: When the requested user does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/auth/password/reset/sms/otp:
    post:
      operationId: sendResetPasswordSMSOTP
      summary: Start reset by SMS OTP
      description: >-
        Starts a password reset flow by sending an SMS OTP. <br><br>**Required
        permissions**: `apps:execute`, `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSendResetPasswordSmsOtpInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSendResetPasswordSmsOtpResponse'
        '403':
          description: >-
            When the phone number of the user is not verified, a forbidden error
            will be returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
        '404':
          description: >-
            When there is no user with the requested phone number as primary
            phone number in the tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/auth/password/reset/sms/otp/validate:
    post:
      operationId: validateResetPasswordSMSOTP
      summary: Validate reset SMS OTP
      description: >-
        Validate a reset password OTP. <br><br>**Required permissions**:
        `apps:execute`, `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiVerifyResetSmsOtpInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidateResetPasswordResponse'
        '403':
          description: When the provided OTP is expired or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
        '404':
          description: When the requested user does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - ClientAccessToken: []
  /v1/auth/password/reset/password/validate:
    post:
      operationId: validateOldPassword
      summary: Start reset by password
      description: >-
        Validates the current password and returns a reset token, which enables
        changing the user`s password
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiResetPasswordByOldPasswordInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidateResetPasswordResponse'
        '403':
          description: When the provided username, password or client_id are incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
  /v1/auth/password/reset:
    post:
      operationId: resetPassword
      summary: Reset password
      description: Resets a user's password
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiResetPasswordInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResetPasswordResponse'
        '400':
          description: >-
            When the new password doesn't meet the password complexity
            requirements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
  /v1/auth/password/validate:
    post:
      operationId: validatePassword
      summary: Validate password
      description: >-
        Validates a new password according to the requesting application's
        password policy. The validation includes checking the password
        complexity (such as minimum length and character requirements) and
        password history (i.e., that the same password wasn't used too
        recently). This can be used before updating a user's password to first
        check that the password they chose is valid and if not, provide feedback
        to the user. <br><br>**Required permissions**: `apps:execute`,
        `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiValidatePasswordInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidatePasswordResponse'
        '403':
          description: When the application does not have password auth method configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenHttpError'
      security:
        - ClientAccessToken: []
  /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:
        - UserAccessToken: []
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
    ApiSendResetPasswordEmailLinkInput:
      type: object
      properties:
        prev_reset_token:
          type: string
          description: >-
            Reset token that contains `mfa_required` as `true`. Should be passed
            when initiating a second factor authentication, in case MFA is
            required for password reset flows.
        ignore_mfa:
          type: boolean
          description: >-
            Allows resetting the password without MFA in case MFA is required
            for password reset flows
        email:
          type: string
          description: >-
            The user's primary email address. Pass either `username` or `email`,
            but not both.
        username:
          type: string
          description: >-
            The username to send the magic link to. Pass either `username` or
            `email`, but not both.
        redirect_uri:
          type: string
          example: https://www.example.com/reset-password
          description: >-
            URI where the email link will redirect to. This is the server GET
            endpoint used to call the password reset 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.
        email_content:
          description: Texts, logo and color to render email template with
          allOf:
            - $ref: '#/components/schemas/EmailContentAttributes'
      required:
        - redirect_uri
    ApiSendResetPasswordEmailResponse:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Reset password email sent
      required:
        - message
    ForbiddenHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 403
      required:
        - message
        - error_code
    NotFoundHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 404
      required:
        - message
        - error_code
    ApiGenerateResetPasswordLinkInput:
      type: object
      properties:
        prev_reset_token:
          type: string
          description: >-
            Reset token that contains `mfa_required` as `true`. Should be passed
            when initiating a second factor authentication, in case MFA is
            required for password reset flows.
        ignore_mfa:
          type: boolean
          description: >-
            Allows resetting the password without MFA in case MFA is required
            for password reset flows
        email:
          type: string
          description: >-
            The user's primary email address. Pass either `username` or `email`,
            but not both.
        username:
          type: string
          description: >-
            The username to send the magic link to. Pass either `username` or
            `email`, but not both.
        redirect_uri:
          type: string
          example: https://www.example.com/reset-password
          description: >-
            URI where the email link will redirect to. This is the server GET
            endpoint used to call the password reset 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.
      required:
        - redirect_uri
    ApiGenerateResetPasswordLinkResponse:
      type: object
      properties:
        reset_link:
          type: string
          readOnly: true
          example: Reset password magic link
      required:
        - reset_link
    ApiSendResetPasswordEmailOtpInput:
      type: object
      properties:
        prev_reset_token:
          type: string
          description: >-
            Reset token that contains `mfa_required` as `true`. Should be passed
            when initiating a second factor authentication, in case MFA is
            required for password reset flows.
        ignore_mfa:
          type: boolean
          description: >-
            Allows resetting the password without MFA in case MFA is required
            for password reset flows
        email:
          type: string
          description: The user's primary email address
        email_content:
          description: Texts, logo and color to render email template with
          allOf:
            - $ref: '#/components/schemas/EmailContentAttributes'
      required:
        - email
    ApiSendResetPasswordEmailOtpResponse:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Email Sent
      required:
        - message
    ApiVerifyResetEmailOtpInput:
      type: object
      properties:
        email:
          type: string
          description: Email address that the OTP was sent to
        passcode:
          type: string
          description: OTP to validate
      required:
        - email
        - passcode
    ApiValidateResetPasswordResponse:
      type: object
      properties:
        result:
          type: string
          description: >-
            Reset token to be used when sending a reset request
            (`/auth/password/reset`)
      required:
        - result
    ApiSendResetPasswordSmsOtpInput:
      type: object
      properties:
        prev_reset_token:
          type: string
          description: >-
            Reset token that contains `mfa_required` as `true`. Should be passed
            when initiating a second factor authentication, in case MFA is
            required for password reset flows.
        ignore_mfa:
          type: boolean
          description: >-
            Allows resetting the password without MFA in case MFA is required
            for password reset flows
        phone_number:
          type: string
          example: '+16175551212'
          description: Phone number to send the SMS to, specified in E.164 format
      required:
        - phone_number
    ApiSendResetPasswordSmsOtpResponse:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: SMS Sent
      required:
        - message
    ApiVerifyResetSmsOtpInput:
      type: object
      properties:
        phone_number:
          type: string
          description: Phone number that the SMS OTP was sent to
        passcode:
          type: string
          description: OTP to validate
      required:
        - phone_number
        - passcode
    ApiResetPasswordByOldPasswordInput:
      type: object
      properties:
        prev_reset_token:
          type: string
          description: >-
            Reset token that contains `mfa_required` as `true`. Should be passed
            when initiating a second factor authentication, in case MFA is
            required for password reset flows.
        username:
          type: string
          description: >-
            The user's username. Pass either `username` or `email`, but not
            both.
        email:
          type: string
          description: >-
            The user's primary email address. Pass either `username` or `email`,
            but not both.
        phone_number:
          type: string
          description: >-
            The user's primary phone number. Pass only one of `username`,
            `email`, or `phone_number`, but not both.
        password:
          type: string
          description: The user's current password
        client_id:
          type: string
      required:
        - password
        - client_id
    ApiPasswordLoginInput:
      type: object
      properties:
        username:
          type: string
          description: >-
            The user's username. Pass either `username` or `email`, but not
            both.
        email:
          type: string
          description: >-
            The user's primary email address. Pass either `username` or `email`,
            but not both.
        phone_number:
          type: string
          description: >-
            The user's primary phone number. Pass only one of `username`,
            `email`, or `phone_number`, but not both.
        password:
          type: string
          description: The user's password
        client_id:
          type: string
          description: >-
            Client ID of the application requesting authentication, retrieved
            from the Transmit Admin Portal
          example: c35ab2a.xVShlOVGsUMh3Cqk73K1O.transmit
        redirect_uri:
          type: string
          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.
          example: https://domain.com/verify
        resource:
          type: string
          description: Resource URI the login is attempting to access.
        require_mfa:
          type: boolean
          example: true
          default: false
          description: Require multi-factor authentication for this authentication request.
        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
      required:
        - password
        - client_id
        - redirect_uri
    ApiResetPasswordRequiredErrorResponse:
      type: object
      properties:
        message:
          type: string
          enum:
            - password_expired
            - temporary_password
          description: Reason the password reset is required
        error_code:
          type: number
          example: 403
        reset_token:
          type: string
          readOnly: true
          description: >-
            Reset token needed to authorize the password reset, if a password
            reset is required
      required:
        - message
        - error_code
        - reset_token
    ApiPasswordLoginResponse:
      type: object
      properties:
        url:
          type: string
          readOnly: true
          description: >-
            URL to start the authentication flow. This is only returned if
            password reset is not required.
    ApiResetPasswordInput:
      type: object
      properties:
        reset_token:
          type: string
          description: >-
            Valid `reset_token` generated from the password login call or by
            initiating a password reset flow
        new_password:
          type: string
          description: The new password
        redirect_uri:
          type: string
          description: >-
            Redirect URI for redirecting the client after a successful password
            change
        resource:
          type: string
          description: Resource to access after successful password change
        require_mfa:
          type: boolean
          example: true
          default: false
          description: Require multi-factor authentication for this authentication request.
      required:
        - reset_token
        - new_password
    ApiResetPasswordResponse:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Password changed successfully
        url:
          type: string
          readOnly: true
          description: URL to start the authorization flow with the new password
        email:
          type: string
          readOnly: true
          description: User email to which the notification will be sent
      required:
        - message
        - url
        - email
    ApiValidatePasswordInput:
      type: object
      properties:
        email:
          type: string
          description: >-
            Email of the user who provided the password. Used to identify the
            user to check password history.
        phone_number:
          type: string
          description: >-
            Phone number of the user who provided the password. Used to identify
            the user to check password history.
        username:
          type: string
          description: >-
            Username of the user who provided the password. Used to identify the
            user to check password history.
        password:
          type: string
          description: Password to validate
      required:
        - password
    ApiValidatePasswordResponse:
      type: object
      properties:
        result:
          description: Result of password validation
          allOf:
            - $ref: '#/components/schemas/ApiValidatePasswordResult'
      required:
        - result
    EmailContentAttributes:
      type: object
      properties:
        subject:
          type: string
          description: The subject of the email
        primaryColor:
          type: string
          example: '#6981FF'
          description: Primary color of the email, specified as a Hex color
        base64logo:
          type: string
          description: >-
            Base64 encoded image for email logo. The string length must be less
            than or equal to 20000 characters
        headerText:
          type: string
          description: The header of the email
        bodyText:
          type: string
          description: The body of the email
        linkText:
          type: string
          description: The text of the link button in the email
        infoText:
          type: string
          description: Any extra information in the email
        footerText:
          type: string
          example: If you didn't request this email, you can safely ignore it.
          description: The footer of the email
        senderName:
          type: string
          description: Name of the sender of the email
      required:
        - subject
    ApiValidatePasswordResult:
      type: object
      properties:
        valid_password:
          type: boolean
          description: Boolean describing if the password is valid for this app and/or user
        errors:
          description: List of issues found with the given password, if validation fails
          type: array
          items:
            $ref: '#/components/schemas/ApiPasswordValidationError'
      required:
        - valid_password
        - errors
    ApiPasswordValidationError:
      type: object
      properties:
        code:
          type: string
          description: Validation issue with given password
        message:
          type: string
          description: Description of the specific problem with the given password
      required:
        - code
        - message
  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.
