{
  "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": "Get authenticators",
        "description": "Retrieves all authenticators for a specific 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_id}/unlock": {
      "post": {
        "operationId": "unlockUserAuthenticator",
        "summary": "Unlock authenticator",
        "description": "Unlocks a user's authenticator by clearing attempts data. Use optional `unlock_type` to limit the unlock operation to a specific lock type, such as `manual` (via Admin Portal or `/lock`) or `automatic` (via lockout policy). Note that TOTP authenticators cannot be unlocked by an authenticator id, use unlock by type instead. <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_id",
            "required": true,
            "in": "path",
            "description": "ID of the authenticator to unlock.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnlockAuthenticatorBodyDto"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "User Unlocked"
          }
        },
        "security": [
          {
            "ClientAccessToken": []
          }
        ]
      }
    },
    "/v1/users/{user_id}/authenticators/types/{authenticator_type}/unlock": {
      "post": {
        "operationId": "unlockUserAuthenticatorByType",
        "summary": "Unlock authenticator by type",
        "description": "Unlocks a user's authenticator by type. Use optional `unlock_type` to limit the unlock operation to a specific lock type, such as `manual` (via Admin Portal or `/lock`) or `automatic` (via lockout policy). Note that TOTP authenticators locked due to the automatic lockout policy cannot be unlocked. <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_magic_link",
                "email_otp",
                "sms_otp",
                "direct_otp",
                "webauthn",
                "password",
                "mobile_biometric",
                "pin_authenticator",
                "face"
              ]
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnlockAuthenticatorBodyDto"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "User Unlocked"
          }
        },
        "security": [
          {
            "ClientAccessToken": []
          }
        ]
      }
    },
    "/v1/users/{user_id}/authenticators/{authenticator_id}/lock": {
      "post": {
        "operationId": "lockUserAuthenticator",
        "summary": "Lock authenticator",
        "description": "Locks a user's authenticator by setting status to Deactivated. <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_id",
            "required": true,
            "in": "path",
            "description": "Authenticator ID to lock.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "description": "Optional body with reason",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LockAuthenticatorInputParams"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Authenticator Locked"
          }
        },
        "security": [
          {
            "ClientAccessToken": []
          }
        ]
      }
    },
    "/v1/users/{user_id}/authenticators/{authenticator_id}": {
      "delete": {
        "operationId": "deleteUserAuthenticator",
        "summary": "Delete authenticator",
        "description": "Deletes a user's authenticator by ID. <br><br>**Required permissions**: `apps:delete`, `[appId]:delete`, `authenticators:delete`.",
        "parameters": [
          {
            "name": "user_id",
            "required": true,
            "in": "path",
            "description": "ID of the user",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "authenticator_id",
            "required": true,
            "in": "path",
            "description": "ID of the authenticator to delete.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Authenticator Deleted"
          }
        },
        "security": [
          {
            "ClientAccessToken": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ApiGetUserAuthenticatorsResponse": {
        "type": "object",
        "properties": {
          "result": {
            "description": "List of user authenticators",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiUserAuthenticatorOutput"
            }
          }
        },
        "required": [
          "result"
        ]
      },
      "UnlockAuthenticatorBodyDto": {
        "type": "object",
        "properties": {
          "unlock_type": {
            "type": "string",
            "description": "Defines the type of lock to clear: `manual` (authenticator locked manually in the Admin Portal or via /lock endpoint) or `automatic` (authenticator locked automatically after failed login attempts as defined by the lockout policy).",
            "enum": [
              "manual",
              "automatic",
              "any"
            ]
          }
        }
      },
      "LockAuthenticatorInputParams": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "description": "Reason for locking"
          }
        }
      },
      "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",
            "deprecated": true
          },
          "app_id": {
            "type": "string"
          },
          "last_accessed_org_id": {
            "type": "string",
            "description": "ID of the last organization the authenticator was used to authenticate for"
          },
          "lockout": {
            "description": "Lockout (applicable only when the authenticator’s status is locked)",
            "allOf": [
              {
                "$ref": "#/components/schemas/ApiUserAuthenticatorLockout"
              }
            ]
          },
          "registering_device": {
            "description": "The device that was used during registration, including device_id and timestamp.",
            "allOf": [
              {
                "$ref": "#/components/schemas/RegisteringDevice"
              }
            ]
          },
          "last_used_devices": {
            "description": "The most recent devices used to authenticate with this authenticator (up to 5, newest first).",
            "maxItems": 5,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LastUsedDevices"
            }
          },
          "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"
        ]
      },
      "LastUsedDevices": {
        "type": "object",
        "properties": {
          "device_id": {
            "type": "string",
            "description": "The device identifier"
          },
          "device_ownership": {
            "type": "string",
            "description": "Device ownership relative to the authenticating user",
            "enum": [
              "user-owned",
              "non-user-owned"
            ]
          },
          "timestamp": {
            "type": "string",
            "description": "Timestamp of the authentication event",
            "format": "date-time"
          }
        },
        "required": [
          "device_id",
          "device_ownership",
          "timestamp"
        ]
      },
      "ApiUserAuthenticatorLockout": {
        "type": "object",
        "properties": {
          "suspended_until": {
            "format": "date-time",
            "type": "string",
            "description": "Lockout remaining time"
          },
          "suspended_at": {
            "format": "date-time",
            "type": "string"
          },
          "remaining_attempts": {
            "type": "number",
            "description": "Remaining attempts"
          },
          "current_tier": {
            "type": "number",
            "description": "Tier number"
          },
          "auto": {
            "type": "boolean",
            "description": "Whether the lockout was triggered automatically and suspension is still active"
          }
        }
      },
      "RegisteringDevice": {
        "type": "object",
        "properties": {
          "device_id": {
            "type": "string",
            "description": "The device ID provided during registration."
          },
          "timestamp": {
            "type": "string",
            "description": "The timestamp when the device was registered.",
            "format": "date-time"
          }
        },
        "required": [
          "device_id",
          "timestamp"
        ]
      },
      "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",
            "deprecated": true
          },
          "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"
          },
          "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": {
          "credential_id": {
            "type": "string",
            "description": "WebAuthn credential ID (passkey ID)"
          },
          "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"
              }
            ]
          },
          "public_key": {
            "type": "string",
            "description": "Public credential key for WebAuthn credentials"
          },
          "passkey_type": {
            "type": "string",
            "enum": [
              "synced",
              "device_bound"
            ],
            "description": "Passkey type, synced across devices or bound to a single device"
          },
          "sync_status": {
            "type": "string",
            "enum": [
              "synced",
              "not_synced"
            ],
            "description": "Backup state of the passkey. Only present for synced passkeys."
          },
          "attestation_status": {
            "type": "string",
            "enum": [
              "attested",
              "unattested"
            ],
            "description": "Reflects certificate chain validation at registration and current FIDO MDS status verification"
          }
        },
        "required": [
          "credential_id",
          "rpId",
          "identifier",
          "devices",
          "public_key"
        ]
      },
      "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"
          },
          "status": {
            "type": "string",
            "description": "The authenticator certificate status"
          }
        }
      }
    },
    "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."
      }
    }
  }
}