openapi: 3.0.3
info:
  title: Verification
  description: Verify user data that will enrich their profile
  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/verification/links/email:
    post:
      operationId: sendVerificationEmail
      summary: Send email link
      description: >-
        Send an email magic link to the given email address. This requires a
        logged-in user so it must be authorized using a valid user access token
        returned upon successful authentication
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSendVerificationEmailInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSendVerificationEmailResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAlreadyVerified'
      security:
        - UserAccessToken: []
  /v1/verification/otp/email/send:
    post:
      operationId: sendVerificationEmailOtp
      summary: Send email OTP
      description: >-
        Send a one-time passcode (OTP) by email to the given email address. This
        requires a logged-in user so it must be authorized using a valid user
        access token returned upon successful authentication.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSendVerificationOtpEmail'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSendEmailResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAlreadyVerified'
      security:
        - UserAccessToken: []
  /v1/verification/otp/email/validate:
    post:
      operationId: verifyEmailOtp
      summary: Validate email OTP
      description: >-
        Validate a one-time passcode (OTP) sent by email. This API is used to
        verify the email OTP sent to the user. The email will be added to the
        user profile and marked as verified. The endpoint will not authenticate
        the user (or create new users), and no tokens are returned.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiValidateVerifyEmailOtpInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiVerifyOtpEmailResponse'
        '400':
          content:
            application/json:
              examples:
                OtpExpired:
                  value:
                    message: Passcode expired
                    error_code: 400
                    error_type: expired_otp
                InvalidEmailOrPasscode:
                  value:
                    message: Invalid email or passcode
                    error_code: 400
                    error_type: invalid_otp
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAlreadyVerified'
      security:
        - UserAccessToken: []
  /v1/verification/otp/sms/send:
    post:
      operationId: sendVerificationSmsOtp
      summary: Send SMS OTP
      description: >-
        Send a one-time passcode (OTP) by SMS to the given phone number. This
        requires a logged-in user so it must be authorized using a valid user
        access token returned upon successful authentication
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSendSmsOtpInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSendVerificationSmsResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberAlreadyVerified'
      security:
        - UserAccessToken: []
  /v1/verification/otp/sms/validate:
    post:
      operationId: verifySmsOtp
      summary: Validate SMS OTP
      description: >-
        Validate a one-time passcode (OTP) sent by SMS. This API is used to
        verify the SMS OTP sent to the user. The phone number will be added to
        the user profile and marked as verified. The endpoint will not
        authenticate the user (or create new users), and no tokens are returned.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiValidateVerificationSmsOtpInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiVerifySMSResponse'
        '400':
          content:
            application/json:
              examples:
                OtpExpired:
                  value:
                    message: Passcode expired
                    error_code: 400
                    error_type: expired_otp
                InvalidPhoneOrPasscode:
                  value:
                    message: Invalid phone number or passcode
                    error_code: 400
                    error_type: invalid_otp
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumberAlreadyVerified'
      security:
        - UserAccessToken: []
components:
  schemas:
    ApiSendVerificationEmailInput:
      type: object
      properties:
        email:
          type: string
          example: name@example.com
          description: Email to send the magic link to
        redirect_uri:
          type: string
          example: https://www.example.com/verify
          description: >-
            URI where the email link will redirect to. The verification result
            will be included as a boolean query parameter called result (for
            example, https://www.example.com/verify?result=true). This URI must
            also be configured as an allowed redirect URI in the Admin Portal.
        email_content:
          description: Texts, logo and color to render email template with
          allOf:
            - $ref: '#/components/schemas/EmailContentAttributes'
        update_primary:
          type: boolean
          description: >-
            Allows the request to update the user's current verified primary
            email. If the user profile already has a verified primary email, it
            will override it if `true` or add it as their secondary email if
            `false`
          default: false
      required:
        - email
        - redirect_uri
    ApiSendVerificationEmailResponse:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Verification email sent
      required:
        - message
    EmailAlreadyVerified:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Email is already verified in the tenant
        error_code:
          type: number
          readOnly: true
          example: 409
      required:
        - message
        - error_code
    ApiSendVerificationOtpEmail:
      type: object
      properties:
        email:
          type: string
          example: name@example.com
          description: Email to send the OTP to
        email_content:
          description: Texts, logo and color to render email template with
          allOf:
            - $ref: '#/components/schemas/EmailContentAttributes'
      required:
        - email
    ApiSendEmailResponse:
      type: object
      properties:
        message:
          type: string
          example: Email sent successfully
      required:
        - message
    NotFoundHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 404
      required:
        - message
        - error_code
    ApiValidateVerifyEmailOtpInput:
      type: object
      properties:
        email:
          type: string
          description: Email that the OTP was sent to
        passcode:
          type: string
          description: Email code to validate
        update_primary:
          type: boolean
          description: >-
            Allows the request to update the user's current verified primary
            email. If the user profile already has a verified primary email, it
            will override it if `true` or add it as their secondary email if
            `false`
          default: false
      required:
        - email
        - passcode
    ApiVerifyOtpEmailResponse:
      type: object
      properties:
        result:
          type: boolean
          readOnly: true
          description: Boolean value indicating if OTP email verification succeeded
      required:
        - result
    ApiSendSmsOtpInput:
      type: object
      properties:
        custom_message:
          type: string
          description: >-
            Message to send, must contain {otp} and {app} placeholders to be
            replaced with one time password and application name. Limited to 140
            characters
        sender_id:
          type: string
          description: >-
            The sender name that appears as the message sender on recipients
            devices. Limited to 11 characters. Limited support see
            https://docs.aws.amazon.com/sns/latest/dg/sns-supported-regions-countries.html
        phone_number:
          type: string
          description: Phone number to send the OTP to
      required:
        - phone_number
    ApiSendVerificationSmsResponse:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: SMS sent
      required:
        - message
    PhoneNumberAlreadyVerified:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Phone number is already verified in the tenant
        error_code:
          type: number
          readOnly: true
          example: 409
      required:
        - message
        - error_code
    ApiValidateVerificationSmsOtpInput:
      type: object
      properties:
        phone_number:
          type: string
          description: Phone number that the SMS OTP was sent to
        passcode:
          type: string
          description: OTP to validate
        update_primary:
          type: boolean
          description: >-
            Allows the request to update the user's current verified primary
            phone number. If the user profile already has a verified primary
            phone number, it will override it if `true` or add it as their
            secondary phone number if `false`
          default: false
      required:
        - phone_number
        - passcode
    ApiVerifySMSResponse:
      type: object
      properties:
        result:
          type: boolean
          readOnly: true
          description: Boolean value indicating if SMS verification succeeded
      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
  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.
