User Factors

The Factors API provides operations to enroll, manage, and verify factors for multifactor authentication (MFA). Manage both administration and end-user accounts, or verify an individual factor at any time.

List all Factors
OAuth 2.0: okta.users.read

Lists all the enrolled factors for the specified user

Request
path Parameters
userId
required
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/factors
Request samples
Response samples
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "factorType": "call",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "profile": { },
    • "provider": "CUSTOM",
    • "status": "ACTIVE",
    • "verify": {
      },
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Enroll a Factor
OAuth 2.0: okta.users.manage

Enrolls a user with a supported factor

Request
path Parameters
userId
required
string
query Parameters
updatePhone
boolean
Default: false
templateId
string

id of SMS template (only for SMS factor)

tokenLifetimeSeconds
integer <int32>
Default: 300
activate
boolean
Default: false
Request Body schema: application/json

Factor

factorType
string (FactorType)
object

Factor-specific attributes

phoneExtension
string
phoneNumber
string
provider
string (FactorProvider)
Enum: "CUSTOM" "DUO" "FIDO" "GOOGLE" "OKTA" "RSA" "SYMANTEC" "YUBICO"
status
string (FactorStatus)
Enum: "ACTIVE" "DISABLED" "ENROLLED" "EXPIRED" "INACTIVE" "NOT_SETUP" "PENDING_ACTIVATION"
object (VerifyFactorRequest)
activationToken
string
answer
string
attestation
string
clientData
string
nextPassCode
string
passCode
string
registrationData
string
stateToken
string
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/factors
Request samples
application/json
{
  • "factorType": "call",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "string"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "verify": {
    • "activationToken": "string",
    • "answer": "string",
    • "attestation": "string",
    • "clientData": "string",
    • "nextPassCode": "string",
    • "passCode": "string",
    • "registrationData": "string",
    • "stateToken": "string"
    }
}
Response samples
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "string"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "verify": {
    • "activationToken": "string",
    • "answer": "string",
    • "attestation": "string",
    • "clientData": "string",
    • "nextPassCode": "string",
    • "passCode": "string",
    • "registrationData": "string",
    • "stateToken": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}

List all Supported Factors
OAuth 2.0: okta.users.read

Lists all the supported factors that can be enrolled for the specified user

Request
path Parameters
userId
required
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/factors/catalog
Request samples
Response samples
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "factorType": "call",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "profile": { },
    • "provider": "CUSTOM",
    • "status": "ACTIVE",
    • "verify": {
      },
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

List all Supported Security Questions
CORS

Lists all available security questions for a user's question factor

Request
path Parameters
userId
required
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/factors/questions
Request samples
Response samples
application/json
[
  • {
    • "answer": "string",
    • "question": "string",
    • "questionText": "string"
    }
]

Retrieve a Factor
OAuth 2.0: okta.users.read

Retrieves a factor for the specified user

Request
path Parameters
userId
required
string
factorId
required
string

id of the Factor

Example: zAgrsaBe0wVGRugDYtdv
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/factors/{factorId}
Request samples
Response samples
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "string"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "verify": {
    • "activationToken": "string",
    • "answer": "string",
    • "attestation": "string",
    • "clientData": "string",
    • "nextPassCode": "string",
    • "passCode": "string",
    • "registrationData": "string",
    • "stateToken": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}

Unenroll a Factor
OAuth 2.0: okta.users.manage

Unenrolls an existing factor for the specified user, allowing the user to enroll a new factor

Request
path Parameters
userId
required
string
factorId
required
string

id of the Factor

Example: zAgrsaBe0wVGRugDYtdv
query Parameters
removeRecoveryEnrollment
boolean
Default: false
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/factors/{factorId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Activate a Factor
OAuth 2.0: okta.users.manage

Activates a factor. The sms and token:software:totp factor types require activation to complete the enrollment process.

Request
path Parameters
userId
required
string
factorId
required
string

id of the Factor

Example: zAgrsaBe0wVGRugDYtdv
Request Body schema: application/json
attestation
string
clientData
string
passCode
string
registrationData
string
stateToken
string
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/factors/{factorId}/lifecycle/activate
Request samples
application/json
{
  • "attestation": "string",
  • "clientData": "string",
  • "passCode": "string",
  • "registrationData": "string",
  • "stateToken": "string"
}
Response samples
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "string"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "verify": {
    • "activationToken": "string",
    • "answer": "string",
    • "attestation": "string",
    • "clientData": "string",
    • "nextPassCode": "string",
    • "passCode": "string",
    • "registrationData": "string",
    • "stateToken": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}

Resend a factor enrollment
OAuth 2.0: okta.users.manage

Resends a factor challenge (SMS/call/email OTP) as part of an enrollment flow. The current rate limit is one OTP challenge (call or SMS) per device every 30 seconds. Okta round-robins between SMS providers with every resend request to help ensure delivery of an SMS OTP across different carriers.

Request
path Parameters
userId
required
string
factorId
required
string

id of the Factor

Example: zAgrsaBe0wVGRugDYtdv
query Parameters
templateId
string

ID of SMS template (only for SMS factor)

Request Body schema: application/json

Factor

factorType
string (FactorType)
object

Factor-specific attributes

phoneExtension
string
phoneNumber
string
provider
string (FactorProvider)
Enum: "CUSTOM" "DUO" "FIDO" "GOOGLE" "OKTA" "RSA" "SYMANTEC" "YUBICO"
status
string (FactorStatus)
Enum: "ACTIVE" "DISABLED" "ENROLLED" "EXPIRED" "INACTIVE" "NOT_SETUP" "PENDING_ACTIVATION"
object (VerifyFactorRequest)
activationToken
string
answer
string
attestation
string
clientData
string
nextPassCode
string
passCode
string
registrationData
string
stateToken
string
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/factors/{factorId}/resend
Request samples
application/json
{
  • "factorType": "call",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "string"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "verify": {
    • "activationToken": "string",
    • "answer": "string",
    • "attestation": "string",
    • "clientData": "string",
    • "nextPassCode": "string",
    • "passCode": "string",
    • "registrationData": "string",
    • "stateToken": "string"
    }
}
Response samples
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "factorType": "call",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "phoneExtension": "string",
    • "phoneNumber": "string"
    },
  • "provider": "CUSTOM",
  • "status": "ACTIVE",
  • "verify": {
    • "activationToken": "string",
    • "answer": "string",
    • "attestation": "string",
    • "clientData": "string",
    • "nextPassCode": "string",
    • "passCode": "string",
    • "registrationData": "string",
    • "stateToken": "string"
    },
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}

Retrieve a Factor Transaction Status
OAuth 2.0: okta.users.read

Retrieves the factors verification transaction status

Request
path Parameters
userId
required
string
factorId
required
string

id of the Factor

Example: zAgrsaBe0wVGRugDYtdv
transactionId
required
string

id of the Transaction

Example: gPAQcN3NDjSGOCAeG2Jv
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/factors/{factorId}/transactions/{transactionId}
Request samples
Response samples
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "factorResult": "CHALLENGE",
  • "factorResultMessage": "string",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}

Verify an MFA Factor
OAuth 2.0: okta.users.manage

Verifies an OTP for a token or token:hardware factor

Request
path Parameters
userId
required
string
factorId
required
string

id of the Factor

Example: zAgrsaBe0wVGRugDYtdv
query Parameters
templateId
string
tokenLifetimeSeconds
integer <int32>
Default: 300
header Parameters
X-Forwarded-For
string
User-Agent
string
Accept-Language
string
Request Body schema: application/json
activationToken
string
answer
string
attestation
string
clientData
string
nextPassCode
string
passCode
string
registrationData
string
stateToken
string
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/factors/{factorId}/verify
Request samples
application/json
{
  • "activationToken": "string",
  • "answer": "string",
  • "attestation": "string",
  • "clientData": "string",
  • "nextPassCode": "string",
  • "passCode": "string",
  • "registrationData": "string",
  • "stateToken": "string"
}
Response samples
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "factorResult": "CHALLENGE",
  • "factorResultMessage": "string",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}