Multi-factor authentication endpoints.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/workos:workos-user-management-multi-factor-authentication-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: WorkOS User Management.multi Factor Authentication API
description: WorkOS REST API
version: '1.0'
contact:
name: WorkOS
url: https://workos.com
email: support@workos.com
license:
name: MIT
url: https://opensource.org/license/MIT
servers:
- url: https://api.workos.com
description: Production
- url: https://api.workos-test.com
description: Staging
security:
- bearer: []
tags:
- name: user-management.multi-factor-authentication
description: Multi-factor authentication endpoints.
x-displayName: User MFA
paths:
/user_management/users/{userlandUserId}/auth_factors:
post:
description: Enrolls a user in a new authentication factor.
operationId: UserlandUserAuthenticationFactorsController_create[0]
parameters:
- name: userlandUserId
required: true
in: path
description: The ID of the [user](/reference/authkit/user).
schema:
example: user_01E4ZCR3C56J083X43JQXF3JK5
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnrollUserlandUserAuthenticationFactorDto'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/UserlandUserAuthenticationFactorEnrollResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
required:
- message
summary: Enroll an Authentication Factor
tags:
- user-management.multi-factor-authentication
get:
description: Lists the authentication factors for a user.
operationId: UserlandUserAuthenticationFactorsController_list[0]
parameters:
- name: userlandUserId
required: true
in: path
description: The ID of the [user](/reference/authkit/user).
schema:
example: user_01E4ZCR3C56J083X43JQXF3JK5
type: string
- name: before
required: false
in: query
description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
schema:
example: obj_1234567890
type: string
- name: after
required: false
in: query
description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
schema:
example: obj_1234567890
type: string
- name: limit
required: false
in: query
description: Upper limit on the number of objects to return, between `1` and `100`.
schema:
minimum: 1
maximum: 100
default: 10
example: 10
type: integer
- name: order
required: false
in: query
description: Order the results by the creation time.
schema:
$ref: '#/components/schemas/PaginationOrder'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserlandUserAuthenticationFactorList'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
required:
- message
summary: List Authentication Factors
tags:
- user-management.multi-factor-authentication
components:
schemas:
AuthenticationChallenge:
type: object
properties:
object:
type: string
description: Distinguishes the authentication challenge object.
const: authentication_challenge
id:
type: string
description: The unique ID of the authentication challenge.
example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ
expires_at:
format: date-time
type: string
description: The timestamp when the challenge will expire. Does not apply to TOTP factors.
example: '2026-01-15T12:00:00.000Z'
code:
type: string
description: The one-time code for the challenge.
example: '123456'
authentication_factor_id:
type: string
description: The unique ID of the authentication factor the challenge belongs to.
example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ
created_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
updated_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
required:
- object
- id
- authentication_factor_id
- created_at
- updated_at
AuthenticationFactor:
type: object
properties:
object:
type: string
description: Distinguishes the authentication factor object.
const: authentication_factor
id:
type: string
description: The unique ID of the factor.
example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ
type:
type: string
enum:
- generic_otp
- sms
- totp
- webauthn
description: The type of the factor to enroll.
example: totp
user_id:
type: string
description: The ID of the [user](/reference/authkit/user).
example: user_01E4ZCR3C56J083X43JQXF3JK5
sms:
type: object
properties:
phone_number:
type: string
description: The user's phone number for SMS-based authentication.
example: '+15005550006'
required:
- phone_number
description: SMS-based authentication factor details.
totp:
type: object
properties:
issuer:
type: string
description: Your application or company name displayed in the user's authenticator app. Defaults to your WorkOS team name.
example: WorkOS
user:
type: string
description: The user's account name displayed in their authenticator app. Defaults to the user's email.
example: user@example.com
required:
- issuer
- user
description: TOTP-based authentication factor details.
created_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
updated_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
required:
- object
- id
- type
- created_at
- updated_at
UserlandUserAuthenticationFactorList:
type: object
properties:
object:
type: string
description: Indicates this is a list response.
const: list
data:
type: array
items:
$ref: '#/components/schemas/AuthenticationFactor'
description: The list of records for the current page.
list_metadata:
type: object
properties:
before:
type:
- string
- 'null'
description: An object ID that defines your place in the list. When the ID is not present, you are at the start of the list.
example: auth_factor_01HXYZ123456789ABCDEFGHIJ
after:
type:
- string
- 'null'
description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
example: auth_factor_01HXYZ987654321KJIHGFEDCBA
required:
- before
- after
description: Pagination cursors for navigating between pages of results.
required:
- object
- data
- list_metadata
EnrollUserlandUserAuthenticationFactorDto:
type: object
properties:
type:
type: string
description: The type of the factor to enroll.
example: totp
const: totp
totp_issuer:
type: string
description: Your application or company name displayed in the user's authenticator app.
example: WorkOS
totp_user:
type: string
description: The user's account name displayed in their authenticator app.
example: user@example.com
totp_secret:
type: string
description: The Base32-encoded shared secret for TOTP factors. This can be provided when creating the auth factor, otherwise it will be generated. The algorithm used to derive TOTP codes is SHA-1, the code length is 6 digits, and the timestep is 30 seconds – the secret must be compatible with these parameters.
example: JBSWY3DPEHPK3PXP
required:
- type
PaginationOrder:
type: string
enum:
- normal
- desc
- asc
example: desc
default: desc
AuthenticationFactorEnrolled:
type: object
properties:
object:
type: string
description: Distinguishes the authentication factor object.
const: authentication_factor
id:
type: string
description: The unique ID of the factor.
example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ
type:
type: string
enum:
- generic_otp
- sms
- totp
- webauthn
description: The type of the factor to enroll.
example: totp
user_id:
type: string
description: The ID of the [user](/reference/authkit/user).
example: user_01E4ZCR3C56J083X43JQXF3JK5
sms:
type: object
properties:
phone_number:
type: string
description: The user's phone number for SMS-based authentication.
example: '+15005550006'
required:
- phone_number
description: SMS-based authentication factor details.
totp:
type: object
properties:
issuer:
type: string
description: Your application or company name displayed in the user's authenticator app. Defaults to your WorkOS team name.
example: WorkOS
user:
type: string
description: The user's account name displayed in their authenticator app. Defaults to the user's email.
example: user@example.com
secret:
type: string
description: TOTP secret that can be manually entered into some authenticator apps in place of scanning a QR code.
example: JBSWY3DPEHPK3PXP
qr_code:
type: string
description: Base64 encoded image containing scannable QR code.
example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
uri:
type: string
description: The `otpauth` URI that is encoded by the provided `qr_code`.
example: otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS
required:
- issuer
- user
- secret
- qr_code
- uri
description: TOTP-based authentication factor details. Includes enrollment secrets only available at creation time.
created_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
updated_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
required:
- object
- id
- type
- created_at
- updated_at
UserlandUserAuthenticationFactorEnrollResponse:
type: object
properties:
authentication_factor:
$ref: '#/components/schemas/AuthenticationFactorEnrolled'
description: The [authentication factor](/reference/authkit/mfa/authentication-factor) object that represents the additional authentication method used on top of the existing authentication strategy.
authentication_challenge:
$ref: '#/components/schemas/AuthenticationChallenge'
description: The [authentication challenge](/reference/authkit/mfa/authentication-challenge) object that is used to complete the authentication process.
required:
- authentication_factor
- authentication_challenge
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
description: 'Your WorkOS API key prefixed with `sk_`. Pass it as a Bearer token: `Authorization: Bearer sk_example_123456789`.'
access_token:
scheme: bearer
bearerFormat: JWT
type: http
description: An SSO access token returned from the Get a Profile and Token endpoint.