{
  "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"
        ]
      },
      "UnlockAuthenticatorInputParams": {
        "type": "object",
        "properties": {
          "authenticator_id": {
            "type": "string",
            "description": "Authenticator ID"
          }
        }
      },
      "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": {
          "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"
          }
        },
        "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"
          }
        }
      }
    },
    "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."
      }
    }
  }
}