--- descriptions: authentication: totp_code: >- The time-based one-time password generated by the factor that was challenged. challenge_id: >- The unique ID of the authentication challenge created for the TOTP factor for which the user is enrolled. reference: curl: - key: authenticate_mfa_totp id: authenticate_mfa_totp url: /reference/authkit/authentication/totp title: /user_management/authenticate type: POST parameters: - key: client_id type: string description: (client_id) - key: client_secret type: string description: (client_secret) - key: grant_type type: '"urn:workos:oauth:grant-type:mfa-totp"' description: (authentication.grant_type) - key: code type: string description: (authentication.totp_code) - key: authentication_challenge_id type: string description: (authentication.challenge_id) - key: pending_authentication_token type: string description: (authentication.pending_authentication_token) - key: ip_address type: string optional: true description: (authentication.ip_address) - key: user_agent type: string optional: true description: (authentication.user_agent) returns: - key: anonymous type: object unwrap: true properties: - key: user type: user description: (user.self) - key: organizationId type: string optional: true description: (authentication.organization_id) - key: authentication_method type: >- "SSO" | "Password" | "AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" | "MicrosoftOAuth" | "MagicAuth" | "Impersonation" optional: false description: (authentication.authentication_method) js: - key: authenticateWithTotp id: authenticate_mfa_totp url: /reference/authkit/authentication/totp title: userManagement.authenticateWithTotp() parameters: - key: clientId type: string description: (client_id) - key: code type: string description: (authentication.totp_code) - key: authenticationChallengeId type: string description: (authentication.challenge_id) - key: pendingAuthenticationToken type: string description: (authentication.pending_authentication_token) - key: ipAddress type: string optional: true description: (authentication.ip_address) - key: userAgent type: string optional: true description: (authentication.user_agent) - key: session type: object optional: true unwrap: true properties: - key: sealSession type: boolean description: (authentication.seal_session) - key: cookiePassword type: string optional: true description: (authentication.cookie_password_seal) returns: - key: anonymous type: object unwrap: true properties: - key: user type: User description: (user.self) - key: organizationId type: string optional: true description: (authentication.organization_id) - key: authenticationMethod type: >- "SSO" | "Password" | "AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" | "MicrosoftOAuth" | "MagicAuth" | "Impersonation" optional: false description: (authentication.authentication_method) - key: sealedSession type: string optional: true description: (authentication.sealed_session) python: - key: authenticate_with_totp id: authenticate_mfa_totp url: /reference/authkit/authentication/totp title: user_management.authenticate_with_totp() parameters: - key: code type: str description: (authentication.totp_code) - key: authentication_challenge_id type: str description: (authentication.challenge_id) - key: pending_authentication_token type: str description: (authentication.pending_authentication_token) - key: ip_address type: str optional: true description: (authentication.ip_address) - key: user_agent type: str optional: true description: (authentication.user_agent) returns: - key: anonymous type: AuthenticationResponse unwrap: true properties: - key: user type: User description: (user.self) - key: organization_id type: str optional: true description: (authentication.organization_id) - key: access_token type: str optional: false description: (authentication.access_token) - key: refresh_token type: str optional: false description: (authentication.refresh_token) go: - key: AuthenticateWithTOTP id: authenticate_mfa_totp url: /reference/authkit/authentication/totp title: usermanagement.AuthenticateWithTOTP() parameters: - (ctx) - key: opts type: usermanagement.AuthenticateWithTOTPOpts unwrap: true properties: - key: ClientID type: string description: (client_id) - key: Code type: string description: (authentication.totp_code) - key: AuthenticationChallengeID type: string description: (authentication.challenge_id) - key: PendingAuthenticationToken type: string description: (authentication.pending_authentication_token) - key: IPAddress type: string optional: true description: (authentication.ip_address) - key: UserAgent type: string optional: true description: (authentication.user_agent) returns: - key: response type: object unwrap: true properties: - key: User type: User description: (user.self) - key: OrganizationID type: string optional: true description: (authentication.organization_id) - (err) php: - key: authenticateWithTotp id: authenticate_mfa_totp url: /reference/authkit/authentication/totp title: $userManagement->authenticateWithTotp() parameters: - key: clientId type: string description: (client_id) - key: code type: string description: (authentication.totp_code) - key: authenticationChallengeId type: string description: (authentication.challenge_id) - key: pendingAuthenticationToken type: string description: (authentication.pending_authentication_token) - key: ipAddress type: string optional: true description: (authentication.ip_address) - key: userAgent type: string optional: true description: (authentication.user_agent) returns: - key: anonymous type: object unwrap: true properties: - key: user type: User description: (user.self) - key: organizationId type: string optional: true description: (authentication.organization_id) ruby: - key: authenticate_with_totp id: authenticate_mfa_totp url: /reference/authkit/authentication/totp title: UserManagement.authenticate_with_totp() parameters: - key: client_id type: String description: (client_id) - key: code type: String description: (authentication.totp_code) - key: authentication_challenge_id type: String description: (authentication.challenge_id) - key: pending_authentication_token type: String description: (authentication.pending_authentication_token) - key: ip_address type: String optional: true description: (authentication.ip_address) - key: user_agent type: String optional: true description: (authentication.user_agent) returns: - key: anonymous type: object unwrap: true properties: - key: user type: User description: (user.self) - key: organization_id type: String optional: true description: (authentication.organization_id) java: - key: authenticateWithTotp id: authenticate_mfa_totp url: /reference/authkit/authentication/totp title: userManagement.authenticateWithTotp() parameters: - key: clientId type: String description: (client_id) - key: code type: String description: (authentication.totp_code) - key: authenticationChallengeId type: String description: (authentication.challenge_id) - key: pendingAuthentication_Token type: String description: (authentication.pending_authentication_token) - key: options type: AuthenticationAdditionalOptionsBuilder optional: true unwrap: true properties: - key: invitationToken type: String optional: true description: (authentication.invitation_token) - key: ipAddress type: String optional: true description: (authentication.ip_address) - key: userAgent type: String optional: true description: (authentication.user_agent) returns: - key: response type: Authentication unwrap: true properties: - key: user type: User optional: true description: (user.self) - key: organizationId type: String optional: true description: (authentication.organization_id) - key: accessToken type: string optional: true description: (authentication.access_token) - key: refreshToken type: string optional: true description: (authentication.refresh_token) - key: impersonator type: AuthenticationImpersonator optional: true properties: - key: email type: String description: (authentication.impersonator.email) - key: reason type: String optional: true description: (authentication.impersonator.reason) originalPath: >- .tmp-workos-clone/packages/docs/content/reference/authkit/authentication/totp.mdx --- ## Authenticate with a time-based one-time password Authenticates a user enrolled into MFA using time-based one-time password (TOTP). Users enrolled into MFA are required to enter a TOTP each time they sign in. When they attempt to authenticate with their credentials, the API will return an [MFA challenge error](/reference/authkit/authentication-errors/mfa-challenge-error) that contains a pending authentication token. To continue with the authentication flow, [challenge](/reference/mfa/challenge/create) one of the factors returned by the MFA challenge error response and present a UI to the user to enter the TOTP code. Then, authenticate the user with the TOTP code, the challenge from the factor, and the pending authentication token from the MFA challenge error. MFA can be enabled via the [Authentication page](https://dashboard.workos.com/authentication) in the WorkOS dashboard.