openapi: 3.0.3
info:
  title: User Authenticators
  description: >-
    Manage user authenticators, such as WebAuthn credentials, TOTP
    authenticators, and more. These APIs allow you to view and manage the
    authenticators that were registered for a given user.
  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/users/{userId}/authenticators:
    get:
      operationId: userAuthenticators
      summary: User authenticators
      description: >-
        List of authenticators for a user. <br><br>**Required permissions**:
        `organizations:read`, `orgs:read`, `users:read`, `apps:read`,
        `[appId]:read`, `authenticators:read`.
      parameters:
        - name: userId
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
      responses:
        '200':
          description: User authenticators object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetUserAuthenticatorsResponse'
      security:
        - ClientAccessToken: []
  /v1/users/{user_id}/authenticators/{authenticator_type}/unlock:
    post:
      operationId: unlockUserAuthenticator
      summary: Unlock authenticator
      description: >-
        Unlocks a user's authenticator by clearing all attempts data for the
        locked user. <br><br>**Required permissions**: `apps:edit`,
        `[appId]:edit`, `authenticators:edit`.
      parameters:
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
        - name: authenticator_type
          required: true
          in: path
          description: Authenticator type to unlock.
          schema:
            type: string
            enum:
              - totp
              - email_otp
              - sms_otp
              - direct_otp
              - webauthn
              - password
              - pin_authenticator
              - face
      responses:
        '204':
          description: User Unlocked
      security:
        - ClientAccessToken: []
components:
  schemas:
    ApiGetUserAuthenticatorsResponse:
      type: object
      properties:
        result:
          description: List of user authenticators
          type: array
          items:
            $ref: '#/components/schemas/ApiUserAuthenticatorOutput'
      required:
        - result
    ApiUserAuthenticatorOutput:
      type: object
      properties:
        id:
          type: string
          description: The ID of the authenticator, autogenerated upon registration
        type:
          type: string
          description: The type of the authenticator
          enum:
            - totp
            - email_magic_link
            - email_otp
            - sms_otp
            - direct_otp
            - webauthn
            - password
            - mobile_biometric
            - pin_authenticator
            - google
            - facebook
            - apple
            - line
            - saml
            - oidc
            - face
        name:
          type: string
          description: The name of the authenticator
        status:
          type: string
          description: >-
            The status of the authenticator. An authenticator is `registered` if
            it hasn't yet been used to authenticate, and `active` if it's been
            used at least once. Admins can update the status to `deactivated` to
            manually block it (either temporarily or permanently) and an
            authenticator can become `locked` by the lockout rules defined in
            its settings.
          enum:
            - Active
            - Deactivated
            - Registered
            - Locked
            - Deleted
        user_id:
          type: string
          description: The ID of the user this authenticator is associated with
        registered_at:
          format: date-time
          type: string
          description: >-
            The date the authenticator was registered. For social login methods,
            this corresponds to the date it was first used to authenticate. For
            email/SMS-based ones, it corresponds to the date the email/phone
            number was added to the user profile.
        last_successful_authentication:
          format: date-time
          type: string
          description: Date this authenticator was last used to successfully authenticate.
        last_failed_authentication:
          format: date-time
          type: string
          description: >-
            The last failed authentication date. For social login and
            email/SMS-based methods, this may corresponds to an authentications
            performed for another app in the tenant.
        last_accessed_app_id:
          type: string
          description: >-
            ID of the last application the authenticator was used to
            authenticate for
        last_accessed_org_id:
          type: string
          description: >-
            ID of the last organization the authenticator was used to
            authenticate for
        extra_data:
          description: Additional data for the authenticator
          oneOf:
            - $ref: '#/components/schemas/ApiEmailMagicLinkExtraData'
            - $ref: '#/components/schemas/ApiEmailOtpExtraData'
            - $ref: '#/components/schemas/ApiSmsOtpExtraData'
            - $ref: '#/components/schemas/ApiTotpExtraData'
            - $ref: '#/components/schemas/ApiGoogleExtraData'
            - $ref: '#/components/schemas/ApiFacebookExtraData'
            - $ref: '#/components/schemas/ApiAppleExtraData'
            - $ref: '#/components/schemas/ApiLineExtraData'
            - $ref: '#/components/schemas/ApiSamlExtraData'
            - $ref: '#/components/schemas/ApiOidcExtraData'
            - $ref: '#/components/schemas/ApiPasswordExtraData'
            - $ref: '#/components/schemas/ApiWebauthnExtraData'
            - $ref: '#/components/schemas/ApiMobileBiometricExtraData'
            - $ref: '#/components/schemas/ApiPinAuthenticatorExtraData'
      required:
        - id
        - type
        - status
        - registered_at
    ApiEmailMagicLinkExtraData:
      type: object
      properties:
        email:
          type: string
          description: The email address
        verified:
          type: boolean
          description: Indicates whether the email was verified
        verified_at:
          format: date-time
          type: string
          description: The date the email was verified
      required:
        - email
        - verified
        - verified_at
    ApiEmailOtpExtraData:
      type: object
      properties:
        email:
          type: string
          description: The email address
        verified:
          type: boolean
          description: Indicates whether the email was verified
        verified_at:
          format: date-time
          type: string
          description: The date the email was verified
      required:
        - email
        - verified
        - verified_at
    ApiSmsOtpExtraData:
      type: object
      properties:
        phone_number:
          type: string
          description: The phone number
        verified:
          type: boolean
          description: Indicates whether the phone number was verified
        verified_at:
          format: date-time
          type: string
          description: The date the phone number was verified
      required:
        - phone_number
        - verified
        - verified_at
    ApiTotpExtraData:
      type: object
      properties:
        email:
          type: string
          description: The email address of the user
        phone_number:
          type: string
          description: The phone number of the user
        username:
          type: string
          description: The username of the user
        digits:
          type: number
          description: The number of digits in the token
        period:
          type: number
          description: The period of time the token is valid for
        algorithm:
          type: string
          description: The algorithm used to generate the token
        issuer:
          type: string
          description: The issuer of the token
      required:
        - digits
        - period
        - algorithm
        - issuer
    ApiGoogleExtraData:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier of the user in the social network
        email:
          type: string
          description: The email address
      required:
        - identifier
        - email
    ApiFacebookExtraData:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier of the user in the social network
        email:
          type: string
          description: The email address
      required:
        - identifier
        - email
    ApiAppleExtraData:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier of the user in the social network
        email:
          type: string
          description: The email address
      required:
        - identifier
        - email
    ApiLineExtraData:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier of the user in the social network
        email:
          type: string
          description: The email address
      required:
        - identifier
        - email
    ApiSamlExtraData:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier of the user in the social network
        email:
          type: string
          description: The email address
      required:
        - identifier
        - email
    ApiOidcExtraData:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier of the user in the social network
        email:
          type: string
          description: The email address
      required:
        - identifier
        - email
    ApiPasswordExtraData:
      type: object
      properties:
        app_id:
          type: string
          description: The app id
        app_name:
          type: string
          description: The name of the app
        updated_at:
          format: date-time
          type: string
          description: The date the password was last updated
        created_at:
          format: date-time
          type: string
          description: The date the password was created
        email:
          type: string
          description: The email address of the user
        phone_number:
          type: string
          description: The phone number of the user
        username:
          type: string
          description: The username of the user
        expired:
          type: boolean
          description: Whether the password is currently expired
        temporary:
          type: boolean
          description: Whether the password is temporary and must be reset after first use
        expires_in:
          format: date-time
          type: string
          description: The date the password will be expired
      required:
        - app_id
        - updated_at
        - expired
        - temporary
    ApiWebauthnExtraData:
      type: object
      properties:
        rpId:
          type: string
          description: Relying Party ID
        identifier:
          type: string
          description: The user identifier
        devices:
          description: List of devices
          type: array
          items:
            $ref: '#/components/schemas/ApiUserWebauthnDeviceMetadataDto'
        aaguid_info:
          description: The authenticator's AAGUID Information
          allOf:
            - $ref: '#/components/schemas/AAGUIDInfo'
      required:
        - rpId
        - identifier
        - devices
    ApiMobileBiometricExtraData:
      type: object
      properties:
        algorithm:
          type: string
          description: The type of biometric
        origin:
          type: string
          description: The origin of the biometric
      required:
        - algorithm
        - origin
    ApiPinAuthenticatorExtraData:
      type: object
      properties:
        algorithm:
          type: string
          description: The type of biometric
        origin:
          type: string
          description: The origin of the biometric
        displayName:
          type: string
          description: The display name of the biometric
      required:
        - algorithm
        - origin
        - displayName
    ApiUserWebauthnDeviceMetadataDto:
      type: object
      properties:
        os_type:
          type: string
          description: Device OS type
        os_version:
          type: string
          description: Device OS version
        browser:
          type: string
          description: Browser name
        user_agent:
          type: string
          description: User agent
        first_seen:
          type: string
          description: Date the credential was first used by this device, in ISO 8601
        last_seen:
          type: string
          description: Date the credential was last used by this device, in ISO 8601
      required:
        - os_type
        - os_version
        - browser
        - user_agent
        - first_seen
        - last_seen
    AAGUIDInfo:
      type: object
      properties:
        aaguid:
          type: string
          description: The authenticator AAGUID
        passkey_provider_name:
          type: string
          description: The authenticator name
  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.
