On This Page

Authentication API

The Okta Authentication API provides operations to authenticate users, perform multifactor enrollment and verification, recover forgotten passwords, and unlock accounts. It can be used as a standalone API to provide the identity layer on top of your existing application, or it can be integrated with the Okta Sessions API to obtain an Okta session cookie and access apps within Okta.

The API is targeted for developers who want to build their own end-to-end login experience to replace the built-in Okta login experience and addresses the following key scenarios:

  • Primary authentication allows you to verify username and password credentials for a user.
  • Multifactor authentication (MFA) strengthens the security of password-based authentication by requiring additional verification of another Factor such as a temporary one-time password or an SMS passcode. The Authentication API supports user enrollment with MFA factors enabled by the administrator, as well as MFA challenges based on your Okta Sign-On Policy.
  • Recovery allows users to securely reset their password if they've forgotten it, or unlock their account if it has been locked out due to excessive failed login attempts. This functionality is subject to the security policy set by the administrator.

Application types

The behavior of the Okta Authentication API varies depending on the type of your application and your org's security policies such as the Okta Sign-On Policy, MFA Enrollment Policy, or Password Policy.

Note: Policy evaluation is conditional on the client request context such as IP address.

Public application

A public application is an application that anonymously starts an authentication or recovery transaction without an API token, such as the Okta Sign-In Widget. Public applications are aggressively rate-limited to prevent abuse and require primary authentication to be successfully completed before releasing any metadata about a user.

Trusted application

Trusted applications are backend applications that act as authentication broker or login portal for your Okta organization and may start an authentication or recovery transaction with an administrator API token. Trusted apps may implement their own recovery flows and primary authentication process and may receive additional metadata about the user before primary authentication has successfully completed.

Note: Trusted web applications may need to override the client request context to forward the originating client context for the user.

Get started with authentication

  1. Make sure that you need the API. Check out the Okta Sign-In Widget which is built on the Authentication API. The Sign-In Widget is easier to use and supports basic use cases.

  2. For more advanced use cases, learn the Okta API basics.

  3. Explore the Authentication API:

    Run in Postman

Authentication operations

Primary authentication

POST /api/v1/authn

Every authentication transaction starts with primary authentication which validates a user's primary password credential. Password Policy, MFA Policy, and Sign-On Policy are evaluated during primary authentication to determine if the user's password is expired, a Factor should be enrolled, or additional verification is required. The transaction state of the response depends on the user's status, group memberships and assigned policies.

The requests and responses vary depending on the application type, and whether a password expiration warning is sent:

Note: You must first enable MFA factors and assign a valid Sign-On Policy to a user to enroll and/or verify a MFA Factor during authentication.

Request parameters for primary authentication

As part of the authentication call either the username and password or the token parameter must be provided.

Parameter Description Param Type DataType Required MaxLength
audience App ID of the target app the user is signing into Body String FALSE
context Provides additional context for the authentication transaction Body Context object FALSE
options Opt-in features for the authentication transaction Body Options object FALSE
password User's password credential Body String FALSE
token Token received as part of activation user request Body String FALSE
username User's non-qualified short-name (for example: dade.murphy) or unique fully-qualified sign in name (for example: dade.murphy@example.com) Body String FALSE
Options object

The authentication transaction state machine can be modified via the following opt-in features:

Property Description DataType Nullable Unique Readonly
multiOptionalFactorEnroll Transitions transaction back to MFA_ENROLL state after successful Factor enrollment when additional optional factors are available for enrollment Boolean TRUE FALSE FALSE
warnBeforePasswordExpired Transitions transaction to PASSWORD_WARN state before SUCCESS if the user's password is about to expire and within their password policy warn period Boolean TRUE FALSE FALSE
Context object

The context object allows trusted web applications such as an external portal to pass additional context for the authentication or recovery transaction.

Note: Overriding context such as deviceToken is a highly privileged operation limited to trusted web applications and requires making authentication or recovery requests with a valid administrator API token. If an API token is not provided, the deviceToken will be ignored.

Property Description DataType Nullable Unique Readonly MinLength MaxLength
deviceToken A globally unique ID identifying the user's client device or user agent String TRUE FALSE FALSE 32

Note: You must always pass the same deviceToken for a user's device with every authentication request for per-device or per-session Sign-On Policy Factor challenges. If the deviceToken is absent or does not match the previous deviceToken, the user is challenged every-time instead of per-device or per-session.

Similarly, you must always pass the same deviceToken for a user's device with every authentication request for new device security behavior detection. If the deviceToken is absent or doesn't match a recent deviceToken for the user, the request is considered to be from a new device. See New Device Behavior Detection.

Device Token Best Practices

Use the following recommendations as guidelines for generating and storing a deviceToken for both web and native applications.

Web Apps
Okta recommends that you generate a UUID or GUID for each client and persist the deviceToken using a secure, HTTP-only cookie or HTML5 localStorage scoped to the customer's domain as the default implementation. See Cookie flags that matter for more best practices on hardening HTTP cookies.

Native Apps
Ask the device operating system for a unique device ID. See Apple's information on DeviceCheck for an example.

Response parameters

Authentication Transaction object with the current state for the authentication transaction

401 Unauthorized status code is returned for requests with invalid credentials, locked out accounts or access denied by sign-on policy.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": "E0000004",
  "errorSummary": "Authentication failed",
  "errorLink": "E0000004",
  "errorId": "oaeuHRrvMnuRga5UzpKIOhKpQ",
  "errorCauses": []
}

429 Too Many Requests status code may be returned when the rate-limit is exceeded.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-Rate-Limit-Limit: 1
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 1447534590

{
    "errorCode": "E0000047",
    "errorSummary": "API call exceeded rate limit due to too many requests.",
    "errorLink": "E0000047",
    "errorId": "oaeWaNHfOyQSES34-a2Dw6Phw",
    "errorCauses": []
}

Primary authentication with public application

Authenticates a user with username/password credentials via a public application

Request example for primary authentication with public application
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "username": "dade.murphy@example.com",
  "password": "correcthorsebatterystaple",
  "options": {
    "multiOptionalFactorEnroll": false,
    "warnBeforePasswordExpired": false
  }
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for primary authentication with public application (success)

Users with a valid password not assigned to a Sign-On Policy with additional verification requirements will successfully complete the authentication transaction.

{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}
Response example for primary authentication with public application (invalid credentials)

401 Unauthorized status code is returned for requests with invalid credentials or when access is denied based on sign-on policy.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": "E0000004",
  "errorSummary": "Authentication failed",
  "errorLink": "E0000004",
  "errorId": "oaeuHRrvMnuRga5UzpKIOhKpQ",
  "errorCauses": []
}
Response example for primary authentication with public application (locked out)

Primary authentication requests for a user with LOCKED_OUT status is conditional on the user's password policy. Password policies define whether to hide or show lockout failures which disclose a valid user identifier to the caller.

Response example for primary authentication with public application and hide lockout failures (Default)

If the user's password policy is configured to hide lockout failures, a 401 Unauthorized error is returned preventing information disclosure of a valid user identifier.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": "E0000004",
  "errorSummary": "Authentication failed",
  "errorLink": "E0000004",
  "errorId": "oaeuHRrvMnuRga5UzpKIOhKpQ",
  "errorCauses": []
}
Response example for primary authentication with public application and show lockout failures

If the user's password policy is configure to show lockout failures, the authentication transaction completes with LOCKED_OUT status.

{
  "status": "LOCKED_OUT",
  "_links": {
    "next": {
      "name": "unlock",
      "href": "https://${yourOktaDomain}/api/v1/authn/recovery/unlock",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Response example for primary authentication with public application and expired password

User must change their expired password to complete the authentication transaction.

Note: Users are challenged for MFA (MFA_REQUIRED) before PASSWORD_EXPIRED if they have an active Factor enrollment.

{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "PASSWORD_EXPIRED",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "policy": {
      "complexity": {
        "minLength": 8,
        "minLowerCase": 1,
        "minUpperCase": 1,
        "minNumber": 1,
        "minSymbol": 0
      }
    }
  },
  "_links": {
    "next": {
      "name": "changePassword",
      "href": "https://${yourOktaDomain}/api/v1/authn/credentials/change_password",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Response example for primary authentication with public application (Factor challenge)

User is assigned to a Sign-On Policy that requires additional verification and must select and verify a previously enrolled Factor by id to complete the authentication transaction.

{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_REQUIRED",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": [
      {
        "id": "rsalhpMQVYKHZKXZJQEW",
        "factorType": "token",
        "provider": "RSA",
        "profile": {
          "credentialId": "dade.murphy@example.com"
        },
        "_links": {
          "verify": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors/rsalhpMQVYKHZKXZJQEW/verify",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        }
      },
      {
        "id": "ostfm3hPNYSOIOIVTQWY",
        "factorType": "token:software:totp",
        "provider": "OKTA",
        "profile": {
          "credentialId": "dade.murphy@example.com"
        },
        "_links": {
          "verify": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors/ostfm3hPNYSOIOIVTQWY/verify",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        }
      },
      {
        "id": "sms193zUBEROPBNZKPPE",
        "factorType": "sms",
        "provider": "OKTA",
        "profile": {
          "phoneNumber": "+1 XXX-XXX-1337"
        },
        "_links": {
          "verify": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors/sms193zUBEROPBNZKPPE/verify",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        }
      },
      {
         "id": "clf193zUBEROPBNZKPPE",
         "factorType": "call",
         "provider": "OKTA",
         "profile": {
           "phoneNumber": "+1 XXX-XXX-1337"
         },
         "_links": {
           "verify": {
             "href": "https://${yourOktaDomain}/api/v1/authn/factors/clf193zUBEROPBNZKPPE/verify",
             "hints": {
               "allow": [
                 "POST"
                ]
              }
            }
         }
      },
      {
        "id": "opf3hkfocI4JTLAju0g4",
        "factorType": "push",
        "provider": "OKTA",
        "profile": {
          "credentialId": "dade.murphy@example.com",
          "deviceType": "SmartPhone_IPhone",
          "name": "Gibson",
          "platform": "IOS",
          "version": "9.0"
        },
        "_links": {
          "verify": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors/opf3hkfocI4JTLAju0g4/verify",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        }
      }
    ]
  },
  "_links": {
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Response example for primary authentication with public application (Factor enroll)

User is assigned to a MFA Policy that requires enrollment during sign-in and must select a Factor to enroll to complete the authentication transaction.

{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": [
      {
        "factorType": "token",
        "provider": "RSA",
        "vendorName": "RSA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "token:software:totp",
        "provider": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "sms",
        "provider": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "call",
        "provider": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
               ]
            }
          }
         },
         "status": "NOT_SETUP",
         "enrollment": "OPTIONAL"
      },
      {
        "factorType": "push",
        "provider": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      }
    ]
  },
  "_links": {
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Primary authentication with trusted application

Authenticates a user via a trusted application or proxy that overrides client request context

Notes:

  • Specifying your own deviceToken is a highly privileged operation limited to trusted web applications and requires making authentication requests with a valid API token. If an API token is not provided, the deviceToken will be ignored.
  • The public IP address of your trusted application must be whitelisted as a gateway IP address to forward the user agent's original IP address with the X-Forwarded-For HTTP header.
Request example for trusted application
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36" \
-H "X-Forwarded-For: 23.235.46.133" \
-d '{
  "username": "dade.murphy@example.com",
  "password": "correcthorsebatterystaple",
  "options": {
    "multiOptionalFactorEnroll": false,
    "warnBeforePasswordExpired": false
  },
  "context": {
    "deviceToken": "26q43Ak9Eh04p7H6Nnx0m69JqYOrfVBY"
  }
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for trusted application
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Primary authentication with activation token

Authenticates a user via a trusted application or proxy that overrides the client request context

Notes:

  • Specifying your own deviceToken is a highly privileged operation limited to trusted web applications and requires making authentication requests with a valid API token. If an API token is not provided, the deviceToken is ignored.
  • The public IP address of your trusted application must be whitelisted as a gateway IP address to forward the user agent's original IP address with the X-Forwarded-For HTTP header.
Request example for activation token
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36" \
-H "X-Forwarded-For: 23.235.46.133" \
-d '{
  "token": "o7AFoTGE9xjQiHQK6dAa"
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for activation token (success - user with password, no MFA)
{
  "expiresAt": "2017-03-29T21:42:30.000Z",
  "status": "SUCCESS",
  "sessionToken": "20111DuMTdPoBlMOqX5R_OAV3ku2bTWxP6wUIRT_jqkU6XTvOsJLmDq",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2017-03-29T21:37:25.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}
Response example for activation token (success - user with password and configured MFA)
{
  "stateToken": "00bMktAiPaI0Jo97bpiKxEw7drTgtukJKs33abrSpb",
  "expiresAt": "2017-03-29T21:49:09.000Z",
  "status": "MFA_ENROLL",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2017-03-29T21:37:25.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": [
      {
        "factorType": "question",
        "provider": "OKTA",
        "vendorName": "OKTA",
        "_links": {
          "questions": {
            "href": "https://${yourOktaDomain}/api/v1/users/00u1nehnZ6qp4Qy8G0g4/factors/questions",
            "hints": {
              "allow": [
                "GET"
              ]
            }
          },
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "token:software:totp",
        "provider": "OKTA",
        "vendorName": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "token:software:totp",
        "provider": "GOOGLE",
        "vendorName": "GOOGLE",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "sms",
        "provider": "OKTA",
        "vendorName": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "push",
        "provider": "OKTA",
        "vendorName": "OKTA",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      },
      {
        "factorType": "token:hardware",
        "provider": "YUBICO",
        "vendorName": "YUBICO",
        "_links": {
          "enroll": {
            "href": "https://${yourOktaDomain}/api/v1/authn/factors",
            "hints": {
              "allow": [
                "POST"
              ]
            }
          }
        },
        "status": "NOT_SETUP",
        "enrollment": "OPTIONAL"
      }
    ]
  },
  "_links": {
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Response example for activation token (success - user without password)

In the case where the user was created without credentials the response will trigger the workflow to set the user's password. After the password is configured, depending on the MFA setting, the workflow continues with MFA enrollment or a successful authentication completes.

{
  "stateToken": "005Oj4_rx1yAYP2MFNobMXlM2wJ3QEyzgifBd_T6Go",
  "expiresAt": "2017-03-29T21:35:47.000Z",
  "status": "PASSWORD_RESET",
  "recoveryType": "ACCOUNT_ACTIVATION",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "policy": {
      "expiration": {
        "passwordExpireDays": 5
      },
      "complexity": {
        "minLength": 8,
        "minLowerCase": 1,
        "minUpperCase": 1,
        "minNumber": 1,
        "minSymbol": 0
      }
    }
  },
  "_links": {
    "next": {
      "name": "resetPassword",
      "href": "https://${yourOktaDomain}/api/v1/authn/credentials/reset_password",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Response example for activation token (failure - invalid or expired token)
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": "E0000004",
  "errorSummary": "Authentication failed",
  "errorLink": "E0000004",
  "errorId": "oae2fYYJmkuTg-NyozqBkb3sw",
  "errorCauses": []
}

Primary authentication with device fingerprinting

Include the X-Device-Fingerprint header to supply a device fingerprint. The X-Device-Fingerprint header is used in the following ways:

  • If the new or unknown device email notification is enabled, an email is sent to the user if the device fingerprint sent in the X-Device-Fingerprint header isn't associated with a previously successful user sign in. For more information about this feature, see the General Security documentation.
  • If you have the security behavior detection feature enabled and you have a new device behavior configured in a policy rule, a new device is detected if the device fingerprint sent in the X-Device-Fingerprint header isn't associated with a previously successful user sign in. See New Device Behavior Detection.

Specifying your own device fingerprint in the X-Device-Fingerprint header is a highly privileged operation that is limited to trusted web applications and requires making authentication requests with a valid API token. You should send the device fingerprint only if the trusted app has a computed fingerprint for the end user's client.

Note: The X-Device-Fingerprint header is different from the device token. Device-based MFA in the Okta Sign-On policy rules depends on the device token only and not on the X-Device-Fingerprint header. To read more about the device token, see Context Object. Device-based MFA would work only if you pass the device token in the client request context.

Device Fingerprint Best Practices

Use the following recommendations as guidelines for generating and storing a device fingerprint in the X-Device-Fingerprint header for both web and native applications.

Web Apps
Okta recommends using a secure, HTTP-only cookie with a random/unique value on the customer's domain as the default implementation. See Cookie flags that matter for more best practices on hardening HTTP cookies.

Native Apps
Ask the device operating system for a unique device ID. See Apple's information on DeviceCheck for an example.

Request example for device fingerprinting
curl -v -X POST \
-H 'Accept: application/json' \
-H 'Authorization: SSWS ${api_token}' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-Fowarded-For: 23.235.46.133' \
-H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36" \
-H 'X-Device-Fingerprint: ${device_fingerprint}' \
-d '{
  "username": "${username}",
  "password" : "${password}",
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for device fingerprinting
{
    "expiresAt": "2018-04-26T17:14:17.000Z",
    "status": "SUCCESS",
    "sessionToken": "20111Il76Eaub0eKNkLGwMUDg5D7dBSN9d_FO-0o7eHKQMyqV7VoqzZ",
    "_embedded": {
        "user": {
            "id": "00ue5f54sbR7dFr9i0h7",
            "passwordChanged": "2018-04-26T17:06:07.000Z",
            "profile": {
                "login": "saml.jackson@stark.com",
                "firstName": "Saml",
                "lastName": "Jackson",
                "locale": "en",
                "timeZone": "America/Los_Angeles"
            }
        }
    }
}

Primary authentication with password expiration warning

Authenticates a user with a password that is about to expire. The user should change their password to complete the authentication transaction but can choose to skip it.

Notes:

  • The warnBeforePasswordExpired option must be explicitly specified as true to allow the authentication transaction to transition to PASSWORD_WARN status.
  • Non-expired passwords successfully complete the authentication transaction if this option is omitted or is specified as false.
Request example for password expiration warning
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "username": "dade.murphy@example.com",
  "password": "correcthorsebatterystaple",
  "options": {
    "multiOptionalFactorEnroll": false,
    "warnBeforePasswordExpired": true
  }
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for password expiration warning
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "PASSWORD_WARN",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "policy": {
      "expiration": {
        "passwordExpireDays": 5
      },
      "complexity": {
        "minLength": 8,
        "minLowerCase": 1,
        "minUpperCase": 1,
        "minNumber": 1,
        "minSymbol": 0
      }
    }
  },
  "_links": {
    "next": {
      "name": "changePassword",
      "href": "https://${yourOktaDomain}/api/v1/authn/credentials/change_password",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "skip": {
      "name": "skip",
      "href": "https://${yourOktaDomain}/api/v1/authn/skip",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

SP-initiated step-up authentication

Early Access

Notes:

  • This endpoint is currently supported only for SAML-based apps.
  • You must first enable the custom sign-in page for the application before using this API.

Every step-up transaction starts with the user accessing an application. If step-up authentication is required, Okta redirects the user to the custom sign-in page with state token as a request parameter.

For example, if the custom sign-in page is set as https://login.example.com, then Okta will redirect to **https://login.example.com?stateToken=**00BClWr4T-mnIqPV8dHkOQlwEIXxB4LLSfBVt7BxsM. To determine the next step, check the state of the transaction.

Step-up authentication without Okta session

Request example for step-up suthentication without Okta session (get transaction state)
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "stateToken":"00BClWr4T-mnIqPV8dHkOQlwEIXxB4LLSfBVt7BxsM"
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for step-up authentication without Okta session
{
   "stateToken":"00BClWr4T-mnIqPV8dHkOQlwEIXxB4LLSfBVt7BxsM",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T22:51:37.000Z",
   "status":"UNAUTHENTICATED",
   "_embedded":{
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "next":{
         "name":"authenticate",
         "href":"https://${yourOktaDomain}/api/v1/authn",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      }
   }
}
Request example for step-up authentication without Okta session (perform primary authentication)

Primary authentication has to be completed by using the value of stateToken request parameter passed to custom sign-in page.

Note: Okta Sign-On Policy and the related App Sign-On Policy are evaluated after successful primary authentication.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "stateToken":"00BClWr4T-mnIqPV8dHkOQlwEIXxB4LLSfBVt7BxsM",
   "username": "dade.murphy@example.com",
   "password": "correcthorsebatterystaple"
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for step-up authentication without Okta session when MFA isn't required

Note: Sign in to the app by following the next link relation.

{
   "stateToken":"00quAZYqYjXg9DZhS5UzE1wrJuQ6KKb_kzOeH7OGB5",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T23:19:40.000Z",
   "status":"SUCCESS",
   "_embedded":{
      "user":{
         "id":"00ub0oNGTSWTBKOLGLNR",
         "passwordChanged":"2017-03-29T21:37:25.000Z",
         "profile":{
            "login":"dade.murphy@example.com",
            "firstName":"Dade",
            "lastName":"Murphy",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
         }
      },
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "next":{
         "name":"original",
         "href":"https://${yourOktaDomain}/login/step-up/redirect?stateToken=00quAZYqYjXg9DZhS5UzE1wrJuQ6KKb_kzOeH7OGB5",
         "hints":{
            "allow":[
               "GET"
            ]
         }
      }
   }
}

Step-up authentication with Okta session

Request example to get transaction state for step-up authentication with Okta session
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
   "stateToken":"00BClWr4T-mnIqPV8dHkOQlwEIXxB4LLSfBVt7BxsM"
}' "https://${yourOktaDomain}/api/v1/authn"
Response example for Factor enroll for step-up authentication with Okta session

The user is assigned to an MFA Policy that requires enrollment during the sign-in process and must select a Factor to enroll to complete the authentication transaction.

{
   "stateToken":"00zEfSRIpELrl87ndYiHNkvOEbyEPrBmTYuf9dsGLl",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T22:58:09.000Z",
   "status":"MFA_ENROLL",
   "_embedded":{
      "user":{
         "id":"00ub0oNGTSWTBKOLGLNR",
         "passwordChanged":"2017-03-29T21:37:25.000Z",
         "profile":{
            "login":"dade.murphy@example.com",
            "firstName":"Dade",
            "lastName":"Murphy",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
         }
      },
      "factors":[
         {
            "factorType":"sms",
            "provider":"OKTA",
            "vendorName":"OKTA",
            "_links":{
               "enroll":{
                  "href":"https://${yourOktaDomain}/api/v1/authn/factors",
                  "hints":{
                     "allow":[
                        "POST"
                     ]
                  }
               }
            },
            "status":"NOT_SETUP",
            "enrollment": "OPTIONAL"
         }
      ],
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "cancel":{
         "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      }
   }
}
Response example for Factor challenge for step-up authentication with Okta session

User is assigned to a Sign-On Policy or App Sign-On Policy that requires additional verification and must select and verify a previously enrolled Factor by id to complete the authentication transaction.

{
   "stateToken":"00POAgFjELRueYUC1p7GFAmrm32EQa2HXw0_YssJ5J",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T23:07:00.000Z",
   "status":"MFA_REQUIRED",
   "_embedded":{
      "user":{
         "id":"00ub0oNGTSWTBKOLGLNR",
         "passwordChanged":"2017-03-29T21:37:25.000Z",
         "profile":{
            "login":"dade.murphy@example.com",
            "firstName":"Dade",
            "lastName":"Murphy",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
         }
      },
      "factors":[
         {
            "id":"opf1cla0gggOBWxuC1d8",
            "factorType":"push",
            "provider":"OKTA",
            "vendorName":"OKTA",
            "profile":{
               "credentialId":"abcd@okta.com",
               "deviceType":"SmartPhone_Android",
               "keys":[
                  {
                     "kty":"PKIX",
                     "use":"sig",
                     "kid":"default",
                     "x5c":[
                        "Mdkkdfjkdjf"
                     ]
                  }
               ],
               "name":"SM-N9005",
               "platform":"ANDROID",
               "version":"21"
            },
            "_links":{
               "verify":{
                  "href":"https://${yourOktaDomain}/api/v1/authn/factors/opf1cla0yyvOBWxuC1d8/verify",
                  "hints":{
                     "allow":[
                        "POST"
                     ]
                  }
               }
            }
         },
         {
            "id":"smsph8F1esz8LlSjo0g3",
            "factorType":"sms",
            "provider":"OKTA",
            "vendorName":"OKTA",
            "profile":{
               "phoneNumber":"+1 XXX-XXX-3161"
            },
            "_links":{
               "verify":{
                  "href":"https://${yourOktaDomain}/api/v1/authn/factors/smsph8F1esz8LlSjo0g3/verify",
                  "hints":{
                     "allow":[
                        "POST"
                     ]
                  }
               }
            }
         }
      ],
      "policy":{
         "allowRememberDevice":true,
         "rememberDeviceLifetimeInMinutes":1440,
         "rememberDeviceByDefault":false,
         "factorsPolicyInfo": {
             "opf1cla0gggOBWxuC1d8": {
                 "autoPushEnabled": true
             }
         }
      },
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "cancel":{
         "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      }
   }
}
Response example after authentication and MFA are complete for step-up authentication with Okta session

Note: Sign in to the app by following the next link relation.

{
   "stateToken":"00quAZYqYjXg9DZhS5UzE1wrJuQ6KKb_kzOeH7OGB5",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T23:19:40.000Z",
   "status":"SUCCESS",
   "_embedded":{
      "user":{
         "id":"00ub0oNGTSWTBKOLGLNR",
         "passwordChanged":"2017-03-29T21:37:25.000Z",
         "profile":{
            "login":"dade.murphy@example.com",
            "firstName":"Dade",
            "lastName":"Murphy",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
         }
      },
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "next":{
         "name":"original",
         "href":"https://${yourOktaDomain}/login/step-up/redirect?stateToken=00quAZYqYjXg9DZhS5UzE1wrJuQ6KKb_kzOeH7OGB5",
         "hints":{
            "allow":[
               "GET"
            ]
         }
      }
   }
}

IDP-initiated step-up authentication

POST /api/v1/authn

Early Access

Authenticates a user for signing in to the specified application

Notes:

  • Only WS-Federation, SAML based apps are supported.
  • Pass the application instance ID of the app as "audience" along with the user credentials.

Note: Okta Sign-on Policy and the related App Sign-on Policy are evaluated after successful primary authentication.

Request example for IDP-initiated step-up authentication
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "username": "dade.murphy@example.com",
  "password": "correcthorsebatterystaple",
  "audience": "0oa6gva7owNAhDam50h7",
  "options": {
    "multiOptionalFactorEnroll": false,
    "warnBeforePasswordExpired": true
  }
}' "https://${yourOktaDomain}/api/v1/authn"
Response example when MFA isn't required
{
   "stateToken":"00quAZYqYjXg9DZhS5UzE1wrJuQ6KKb_kzOeH7OGB5",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T23:19:40.000Z",
   "status":"SUCCESS",
   "_embedded":{
      "user":{
         "id":"00ub0oNGTSWTBKOLGLNR",
         "passwordChanged":"2017-03-29T21:37:25.000Z",
         "profile":{
            "login":"dade.murphy@example.com",
            "firstName":"Dade",
            "lastName":"Murphy",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
         }
      },
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "next":{
         "name":"original",
         "href":"https://${yourOktaDomain}/login/step-up/redirect?stateToken=00quAZYqYjXg9DZhS5UzE1wrJuQ6KKb_kzOeH7OGB5",
         "hints":{
            "allow":[
               "GET"
            ]
         }
      }
   }
}

Note: Sign in to the app by following the next link relation.

Response example for Factor enroll

The user is assigned to an MFA Policy that requires enrollment during the sign-in process and must select a Factor to enroll to complete the authentication transaction.

{
   "stateToken":"00zEfSRIpELrl87ndYiHNkvOEbyEPrBmTYuf9dsGLl",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T22:58:09.000Z",
   "status":"MFA_ENROLL",
   "_embedded":{
      "user":{
         "id":"00ub0oNGTSWTBKOLGLNR",
         "passwordChanged":"2017-03-29T21:37:25.000Z",
         "profile":{
            "login":"dade.murphy@example.com",
            "firstName":"Dade",
            "lastName":"Murphy",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
         }
      },
      "factors":[
         {
            "factorType":"sms",
            "provider":"OKTA",
            "vendorName":"OKTA",
            "_links":{
               "enroll":{
                  "href":"https://${yourOktaDomain}/api/v1/authn/factors",
                  "hints":{
                     "allow":[
                        "POST"
                     ]
                  }
               }
            },
            "status":"NOT_SETUP",
            "enrollment": "OPTIONAL"
         }
      ],
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "cancel":{
         "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      }
   }
}
Response example for Factor challenge

User is assigned to a Sign-on Policy or App Sign-on Policy that requires additional verification and must select and verify a previously enrolled Factor by id to complete the authentication transaction.

{
   "stateToken":"00POAgFjELRueYUC1p7GFAmrm32EQa2HXw0_YssJ5J",
   "type":"SESSION_STEP_UP",
   "expiresAt":"2017-05-30T23:07:00.000Z",
   "status":"MFA_REQUIRED",
   "_embedded":{
      "user":{
         "id":"00ub0oNGTSWTBKOLGLNR",
         "passwordChanged":"2017-03-29T21:37:25.000Z",
         "profile":{
            "login":"dade.murphy@example.com",
            "firstName":"Dade",
            "lastName":"Murphy",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
         }
      },
      "factors":[
         {
            "id":"opf1cla0gggOBWxuC1d8",
            "factorType":"push",
            "provider":"OKTA",
            "vendorName":"OKTA",
            "profile":{
               "credentialId":"abcd@okta.com",
               "deviceType":"SmartPhone_Android",
               "keys":[
                  {
                     "kty":"PKIX",
                     "use":"sig",
                     "kid":"default",
                     "x5c":[
                        "Mdkkdfjkdjf"
                     ]
                  }
               ],
               "name":"SM-N9005",
               "platform":"ANDROID",
               "version":"21"
            },
            "_links":{
               "verify":{
                  "href":"https://${yourOktaDomain}/api/v1/authn/factors/opf1cla0yyvOBWxuC1d8/verify",
                  "hints":{
                     "allow":[
                        "POST"
                     ]
                  }
               }
            }
         },
         {
            "id":"smsph8F1esz8LlSjo0g3",
            "factorType":"sms",
            "provider":"OKTA",
            "vendorName":"OKTA",
            "profile":{
               "phoneNumber":"+1 XXX-XXX-3161"
            },
            "_links":{
               "verify":{
                  "href":"https://${yourOktaDomain}/api/v1/authn/factors/smsph8F1esz8LlSjo0g3/verify",
                  "hints":{
                     "allow":[
                        "POST"
                     ]
                  }
               }
            }
         }
      ],
      "policy":{
         "allowRememberDevice":true,
         "rememberDeviceLifetimeInMinutes":1440,
         "rememberDeviceByDefault":false,
         "factorsPolicyInfo": {
             "opf1cla0gggOBWxuC1d8": {
                 "autoPushEnabled": true
             }
         }
      },
      "target":{
         "type":"APP",
         "name":"salesforce",
         "label":"Corporate SFDC",
         "_links":{
            "logo":{
               "name":"medium",
               "href":"https://${yourOktaDomain}/assets/img/logos/salesforce_logo.dbd7e0b4de118a1dae1c39d60a3c30e5.png",
               "type":"image/png"
            }
         }
      },
      "authentication":{
         "protocol":"SAML2.0",
         "issuer":{
            "id":"0oa2x5jOopNCpswjo0g4",
            "name":"Corporate SFDC",
            "uri":"exk2x5ixHmk9MBnqz0g4"
         }
      }
   },
   "_links":{
      "cancel":{
         "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      }
   }
}
Response example for invalid or unknown application
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errorCode": "E0000001",
    "errorSummary": "Api validation failed: authRequest",
    "errorLink": "E0000001",
    "errorId": "oae-W6QeEcJQKarRZv8JcmtrA",
    "errorCauses": [
        {
            "errorSummary": "Invalid or unknown audience '0oa6gva7owNAhDam50h7'."
        }
    ]
}
Response example for unsupported application
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errorCode": "E0000001",
    "errorSummary": "Api validation failed: authRequest",
    "errorLink": "E0000001",
    "errorId": "oaelApNWe8WR4uiK7EROTqp-Q",
    "errorCauses": [
        {
            "errorSummary": "Sign in not allowed for app '0oapt2yIp38ySYiMP0g3'."
        }
    ]
}

Change password

POST /api/v1/authn/credentials/change_password

Changes a user's password by providing the existing password and the new password for authentication transactions with either the PASSWORD_EXPIRED or PASSWORD_WARN state

  • A user must change their expired password for an authentication transaction with PASSWORD_EXPIRED status to successfully complete the transaction.
  • A user may opt-out of changing their password (skip) when the transaction has a PASSWORD_WARN status.

Request parameters for change password

Parameter Description Param Type DataType Required
newPassword New password for user Body String TRUE
oldPassword User's current password that is expired or about to expire Body String TRUE
stateToken state token for the current transaction Body String TRUE

Response parameters for change password

Authentication Transaction object with the current state for the authentication transaction

If the oldPassword is invalid you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000014",
  "errorSummary": "Update of credentials failed",
  "errorLink": "E0000014",
  "errorId": "oaeYx8fd_-VQdONMI5OYcqoqw",
  "errorCauses": [
    {
      "errorSummary": "oldPassword: The credentials provided were incorrect."
    }
  ]
}

If the newPassword does not meet password policy requirements, you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000014",
  "errorSummary": "The password does meet the complexity requirements of the current password policy.",
  "errorLink": "E0000014",
  "errorId": "oaeuNNAquYEQkWFnUVG86Abbw",
  "errorCauses": [
    {
      "errorSummary": "Passwords must have at least 8 characters, a lowercase letter, an uppercase letter, a number, no parts of your username"
    }
  ]
}
Request example for change password
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "oldPassword": "correcthorsebatterystaple",
  "newPassword": "Ch-ch-ch-ch-Changes!"
}' "https://${yourOktaDomain}/api/v1/authn/credentials/change_password"
Response example for change password
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Multifactor Authentication operations

You can enroll, activate, manage, and verify factors inside the authentication context with /api/v1/authn/factors.

Note: You can enroll, manage, and verify factors outside the authentication context with /api/v1/users/:uid/factors/.

Enroll Factor

POST /api/v1/authn/factors

CORS

Enrolls a user with a Factor assigned by their MFA Policy

Note: This operation is only available for users that have not previously enrolled a Factor and have transitioned to the MFA_ENROLL state.

Request parameters for enroll Factor

Parameter Description Param Type DataType Required
factorType type of Factor Body Factor Type TRUE
profile profile of a supported Factor Body Factor Profile object TRUE
provider Factor provider Body Provider Type TRUE
stateToken state token for the current transaction Body String TRUE

Response parameters for enroll Factor

Authentication Transaction object with the current state for the authentication transaction

Note: Some Factor types require activation to complete the enrollment process. The authentication transaction transitions to MFA_ENROLL_ACTIVATE if a Factor requires activation.

Enroll Okta Security Question Factor

Enrolls a user with the Okta question Factor and question profile

Note: The Security Question Factor doesn't require activation and is ACTIVE after enrollment.

Request example for enroll Okta Security Question Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "question",
  "provider": "OKTA",
  "profile": {
    "question": "disliked_food",
    "answer": "mayonnaise"
  }
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Okta Security Question Factor
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00OhZsSfoCtbJTrU2XkwntfEl-jCj6ck6qcU_kA049",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Enroll Okta SMS Factor

Enrolls a user with the Okta sms Factor and an SMS profile. A text message with an OTP is sent to the device during enrollment and must be activated by following the next link relation to complete the enrollment process.

Request example for enroll Okta SMS Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "sms",
  "provider": "OKTA",
  "profile": {
    "phoneNumber": "+1-555-415-1337"
  }
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Okta SMS Factor
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "mbl198rKSEWOSKRIVIFT",
      "factorType": "sms",
      "provider": "OKTA",
      "profile": {
        "phoneNumber": "+1 XXX-XXX-1337"
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/mbl198rKSEWOSKRIVIFT/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "sms",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/mbl198rKSEWOSKRIVIFT/lifecycle/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}
Resend SMS as part of enrollment

Use the resend link to send another OTP if the user doesn't receive the original activation SMS OTP.

Notes: The current rate limit is one SMS challenge per device every 30 seconds.

Okta round-robins between SMS providers with every resend request to help ensure delivery of SMS OTP across different carriers.

Request example for resend SMS
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "sms",
  "provider": "OKTA",
  "profile": {
    "phoneNumber": "+1-555-415-1337"
  }
}' "https://${yourOktaDomain}/api/v1/authn/factors/mbl198rKSEWOSKRIVIFT/lifecycle/resend"

Enroll Okta Call Factor

Enrolls a user with the Okta call Factor and a Call profile. A voice call with an OTP is sent to the device during enrollment and must be activated by following the next link relation to complete the enrollment process.

Request example for enroll Okta Call Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "call",
  "provider": "OKTA",
  "profile": {
    "phoneNumber": "+1-555-415-1337"
  }
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Okta Call Factor
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "clf198rKSEWOSKRIVIFT",
      "factorType": "call",
      "provider": "OKTA",
      "profile": {
        "phoneNumber": "+1 XXX-XXX-1337"
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/clf198rKSEWOSKRIVIFT/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "call",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/clf198rKSEWOSKRIVIFT/lifecycle/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}
Resend voice call as part of enrollment

Use the resend link to send another OTP if the user doesn't receive the original activation Voice Call OTP.

Notes: The current rate limit is one voice call challenge per device every 30 seconds.

Okta round-robins between voice call providers with every resend request to help ensure delivery of voice call OTP across different carriers.

Request example for resend voice call
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "call",
  "provider": "OKTA",
  "profile": {
    "phoneNumber": "+1-555-415-1337"
  }
}' "https://${yourOktaDomain}/api/v1/authn/factors/clf198rKSEWOSKRIVIFT/lifecycle/resend"

Enroll Okta Email Factor

Enrolls a user with the Okta email Factor using the user's primary email address. An email message with an OTP is sent to the user during enrollment and must be activated by following the next link relation to complete the enrollment process.

Request example for enroll Okta Email Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "email",
  "provider": "OKTA",
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Okta Email Factor
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "emfultss7bA0V6Z7C0g3",
      "factorType": "email",
      "provider": "OKTA",
      "vendorName": "OKTA",
      "profile": {
        "email": "d...y@example.com"
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/emfultss7bA0V6Z7C0g3/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "email",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/emfultss7bA0V6Z7C0g3/lifecycle/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}

Resend email as part of enrollment

Use the resend link to send another OTP if user doesn't receive the original activation email OTP.

Request example for resend email
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "email",
  "provider": "OKTA",
}' "https://${yourOktaDomain}/api/v1/authn/factors/clf198rKSEWOSKRIVIFT/lifecycle/resend"

Enroll Okta Verify TOTP Factor

Enrolls a user with the Okta token:software:totp Factor. The Factor must be activated after enrollment by following the next link relation to complete the enrollment process.

Note: This API implements the TOTP standard, which is used by apps like Okta Verify and Google Authenticator.

Request example for enroll Okta Verify TOTP Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "token:software:totp",
  "provider": "OKTA"
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Okta Verify TOTP Factor
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "ostf2xjtDKWFPZIKYDZV",
      "factorType": "token:software:totp",
      "provider": "OKTA",
      "profile": {
        "credentialId": "dade.murphy@example.com"
      },
      "_embedded": {
        "activation": {
          "timeStep": 30,
          "sharedSecret": "KBMTM32UJZSXQ2DW",
          "encoding": "base32",
          "keyLength": 6,
          "_links": {
            "qrcode": {
              "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/ostf2xjtDKWFPZIKYDZV/qr/00Mb0zqhJQohwCDkB2wOifajAsAosEAXvDwuCmsAZs",
              "type": "image/png"
            }
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/ostf2xjtDKWFPZIKYDZV/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Enroll Okta Verify Push Factor

Enrolls a user with the Okta verify push Factor. The Factor must be activated on the device by scanning the QR code or visiting the activation link sent via email or sms.

Use the published activation links to embed the QR code or distribute an activation email or sms.

Note: This API implements the TOTP standard, which is used by apps like Okta Verify and Google Authenticator.

Request example for enroll Okta Verify Push Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "push",
  "provider": "OKTA"
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Okta Verify Push Factor
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "factorResult": "WAITING",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "_embedded": {
        "activation": {
          "expiresAt": "2015-11-03T10:15:57.000Z",
          "_links": {
            "qrcode": {
              "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/qr/00fukNElRS_Tz6k-CFhg3pH4KO2dj2guhmaapXWbc4",
              "type": "image/png"
            },
            "send": [
              {
                "name": "email",
                "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/email",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              },
              {
                "name": "sms",
                "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/sms",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              }
            ]
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/poll",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Enroll Google Authenticator Factor

Enrolls a user with the Google token:software:totp Factor. The Factor must be activated after enrollment by following the next link relation to complete the enrollment process.

Request example for enroll Google Authenticator factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "token:software:totp",
  "provider": "GOOGLE"
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Google Authenticator factor
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "ostf2xjtDKWFPZIKYDZV",
      "factorType": "token:software:totp",
      "provider": "GOOGLE",
      "profile": {
        "credentialId": "dade.murphy@example.com"
      },
      "_embedded": {
        "activation": {
          "timeStep": 30,
          "sharedSecret": "KYCRM33UJZSXQ2DW",
          "encoding": "base32",
          "keyLength": 6,
          "_links": {
            "qrcode": {
              "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/uftm3iHSGFQXHCUSDAND/qr/00Mb0zqhJQohwCDkB2wOifajAsAosEAXvDwuCmsAZs",
              "type": "image/png"
            }
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/uftm3iHSGFQXHCUSDAND/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Enroll RSA SecurID factor

Enrolls a user with an RSA SecurID factor and a token profile. RSA tokens must be verified with the current pin+passcode as part of the enrollment request.

Request example for enroll RSA SecurID Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "token",
  "provider": "RSA",
  "profile": {
    "credentialId": "dade.murphy@example.com"
  },
  "passCode": "5275875498"
}' "https://${yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors"
Response example for enroll RSA SecurID Factor
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00OhZsSfoCtbJTrU2XkwntfEl-jCj6ck6qcU_kA049",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Enroll Symantec VIP Factor

Enrolls a user with a Symantec VIP Factor and a token profile. Symantec tokens must be verified with the current and next passcodes as part of the enrollment request.

Request example for enroll Symantec VIP Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "factorType": "token",
  "provider": "SYMANTEC",
  "profile": {
    "credentialId": "VSMT14393584"
  },
  "passCode": "875498",
  "nextPassCode": "678195"
}' "https://${yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors"
Response example for enroll Symantec VIP Factor
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00OhZsSfoCtbJTrU2XkwntfEl-jCj6ck6qcU_kA049",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Enroll YubiKey Factor

Enrolls a user with a Yubico Factor (YubiKey). YubiKeys must be verified with the current passcode as part of the enrollment request.

Request example for enroll YubiKey Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "factorType": "token:hardware",
  "provider": "YUBICO",
  "passCode": "cccccceukngdfgkukfctkcvfidnetljjiknckkcjulji"
}' "https://${yourOktaDomain}/api/v1/users/00u15s1KDETTQMQYABRL/factors"
Response example for enroll YubiKey Factor
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00OhZsSfoCtbJTrU2XkwntfEl-jCj6ck6qcU_kA049",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Enroll Duo Factor

The enrollment process starts with an enrollment request to Okta, then continues with the Duo widget that is embedded in the page. The page needs to create an iframe with the name duo_iframe (described in the Duo documentation) to host the widget. The script address is received in the response object in _embedded.factor._embedded._links.script object. The information to initialize the Duo object is taken from _embedded.factor._embedded.activation object as it is shown in the full example. To maintain the link between Duo and Okta, the stateToken must be passed back when Duo calls the callback. This is done by populating the hidden element in the "duo_form" as it is described here. After Duo enrollment and verification is done, the Duo script makes a call back to Okta. To complete the authentication process, make a call using the poll link to get session token and verify successful state.

Request example for enroll Duo Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "factorType": "web",
  "provider": "DUO",
  "stateToken": "$(stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Response example for enroll Duo Factor
{
  "stateToken":"00BlN4kOtm7wNxuM8nuXsOK1PFXBkvvTH-buJUrgWX",
  "expiresAt":"2016-07-13T13:14:52.000Z",
  "status":"MFA_ENROLL_ACTIVATE",
  "factorResult":"WAITING",
  "_embedded":{
      "user":{
          "id":"00uku2SnbUX49SAGb0g3",
          "passwordChanged":"2016-07-13T13:07:51.000Z",
          "profile":{
              "login":"first.last@gexample.com",
              "firstName":"First",
              "lastName":"Last",
              "locale":"en_US",
              "timeZone":"America/Los_Angeles"
          }
      },
      "factor":{
          "id":"dsflnpo99zpfMyaij0g3",
          "factorType":"web",
          "provider":"DUO",
          "vendorName":"DUO",
          "profile":{
              "credentialId":"first.last@gexample.com"
          },
          "_embedded":{
              "activation":{
                  "host":"api-your-host.duosecurity.com",
                  "signature":"TX|...your-signature",
                  "factorResult":"WAITING",
                  "_links":{
                      "complete":{
                          "href":"https://${yourOktaDomain}/api/v1/authn/factors/dsflnpo99zpfMyaij0g3/lifecycle/duoCallback",
                          "hints":{
                              "allow":[
                                  "POST"
                             ]
                          }
                      },
                      "script":{
                          "href":"https://${yourOktaDomain}/js/sections/duo/Duo-Web-v2.js",
                          "type":"text/javascript; charset=utf-8"
                      }
                  }
              }
          }
      }
  },
  "_links":{
      "next":{
          "name":"poll",
          "href":"https://${yourOktaDomain}/api/v1/authn/factors/dsflnpo99zpfMyaij0g3/lifecycle/activate/poll",
          "hints":{
              "allow":[
                   "POST"
              ]
          }
      },
      "cancel":{
          "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
          "hints":{
              "allow":[
                  "POST"
              ]
          }
      },
      "prev":{
          "href":"https://${yourOktaDomain}/api/v1/authn/previous",
          "hints":{
              "allow":[
                  "POST"
              ]
          }
      }
  }
}

Full page example for Duo enrollment

In this example we put all of the elements together in the html page.

<html>
    <body>
        <!--
            The Duo SDK will automatically bind to this iFrame and populate it for us.
            See https://www.duosecurity.com/docs/duoweb for more info.
         -->
        <iframe id="duo_iframe" width="620" height="330" frameborder="0"></iframe>
        <!--
            The Duo SDK will automatically bind to this form and submit it for us.
            See https://www.duosecurity.com/docs/duoweb for more info.
         -->
        <form method="POST" id="duo_form">
            <!-- The state token is required here (in order to bind anonymous request back into Auth API) -->
            <input type="hidden" name="stateToken" value='00BlN4kOtm7wNxuM8nuXsOK1PFXBkvvTH-buJUrgWX' />
        </form>

        <script src="https://${yourOktaDomain}/js/sections/duo/Duo-Web-v2.js"></script>

        <!-- The host, sig_request, and post_action values will be given via the Auth API -->
        <script>
            Duo.init({
                'host': 'api-your-host.duosecurity.com',
                'sig_request': 'TX|...your-signature',
                'post_action': 'https://${yourOktaDomain}/api/v1/authn/factors/dsflnpo99zpfMyaij0g3/lifecycle/duoCallback'
            });
        </script>
    </body>
</html>
Activation poll request example

Verifies successful authentication and obtains a session token

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "$(stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors/${factorId}/lifecycle/activate/poll"
Activation poll response example
{
  "expiresAt":"2016-07-13T13:37:42.000Z",
  "status":"SUCCESS",
  "sessionToken":"20111zMXPaEe_lEw7pg2Ub810HDkpBwzSVBEPBRpA87LH5sW3Jj35_x",
  "_embedded":{
    "user":{
        "id":"00ukv3jVTgRjDctlX0g3",
        "passwordChanged":"2016-07-13T13:29:58.000Z",
        "profile":{
            "login":"first.last@example.com",
            "firstName":"First",
            "lastName":"Last",
            "locale":"en_US",
            "timeZone":"America/Los_Angeles"
        }
    }
  }
}

Enroll U2F Factor

Enrolls a user with a U2F Factor. The enrollment process starts with getting an appId and nonce from Okta and using those to get registration information from the U2F key using the U2F javascript API.

Note: The appId property in Okta U2F enroll/verify API response is the origin of the web page that triggers the API request (assuming that the origin has been configured to be trusted by Okta). According to the FIDO spec, enrolling and verifying a U2F device with appIds in different DNS zones is not allowed. For example, if a user enrolled a U2F device via the Okta Sign-In Widget that is hosted at https://login.company.com, while the user can verify the U2F Factor from https://login.company.com, the user would not be able to verify it from Okta portal https://company.okta.com. The U2F device would return error code 4 - DEVICE_INELIGIBLE.

Enroll U2F request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "factorType": "u2f",
  "provider": "FIDO",
  "stateToken": "$(stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Enroll U2F response example
{
  "stateToken": "00s7Yewe3Z4aujPLpR4qW4y1hMKzAbyXK5LSKJRW2G",
  "expiresAt": "2016-12-05T19:40:53.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "_embedded": {
    "user": {
      "id": "00ukv3jVTgRjDctlX0g3",
      "passwordChanged": "2015-10-28T23:27:57.000Z",
      "profile": {
        "login": "first.last@gmail.com",
        "firstName": "First",
        "lastName": "Last",
        "locale": "en",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "fuf8y1y14jaygfX5K0h7",
      "factorType": "u2f",
      "provider": "FIDO",
      "vendorName": "FIDO",
      "_embedded": {
        "activation": {
          "version": "U2F_V2",
          "appId": "https://${yourOktaDomain}",
          "nonce": "s-NaltFnye-xNsJeAhnN",
          "timeoutSeconds": 20
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/fuf8y1y14jaygfX5K0h7/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Enroll WebAuthn Factor

Note: The WebAuthN Factor is available for those using the Okta-hosted Custom Sign-In Page. If you are using a self-hosted, customized sign-in widget, you must first upgrade to widget version 3.4.0 and enable the configuration option.

Enrolls a user with a WebAuthn Factor. The enrollment process starts with getting the WebAuthn credential creation options, which are used to help select an appropriate authenticator using the WebAuthn API. This authenticator then generates an enrollment attestation that may be used to register the authenticator for the user.

Enroll WebAuthn request parameters
Parameter Description Param Type DataType Required
stateToken state token for the current transaction Body String TRUE
Enroll WebAuthn response parameters

In the embedded resources object, the factor._embedded.activation object contains properties used to guide the client in creating a new WebAuthn credential for use with Okta.

For more information about these credential creation options, see the WebAuthn spec for PublicKeyCredentialCreationOptions.

Note: Additionally, the activation object contains a u2fParams object with an appid property. This deprecated legacy property was used to support backwards compatibility with U2F and is no longer in use.

Enroll WebAuthn request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "factorType": "webauthn",
  "provider": "FIDO",
  "stateToken": "$(stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors"
Enroll WebAuthn response example
{
  "stateToken": "00IzlXt68vyoh3r6rtv9JWXLwSuVkM6_AP65f-Actj",
  "expiresAt": "2016-12-05T19:40:53.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "_embedded": {
    "user": {
      "id": "00ukv3jVTgRjDctlX0g3",
      "passwordChanged": "2015-10-28T23:27:57.000Z",
      "profile": {
        "login": "first.last@gmail.com",
        "firstName": "First",
        "lastName": "Last",
        "locale": "en",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "fwfbaopNw5CCGJTu20g4",
      "factorType": "webauthn",
      "provider": "FIDO",
      "vendorName": "FIDO",
      "_embedded": {
        "activation": {
          "attestation": "direct",
          "authenticatorSelection": {
            "userVerification": "preferred",
            "requireResidentKey": false
          },
          "challenge": "cdsZ1V10E0BGE9GcG3IK",
          "excludeCredentials": [],
          "pubKeyCredParams": [
            {
              "type": "public-key",
              "alg": -7
            },
            {
              "type": "public-key",
              "alg": -257
            }
          ],
          "rp": {
            "name":"Rain-Cloud59"
          },
          "u2fParams": {
            "appid": "https://${yourOktaDomain}.com"
          },
          "user": {
            "displayName": "First Last",
            "name": "first.last@gmail.com",
            "id": "00ukv3jVTgRjDctlX0g3"
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/fwfbaopNw5CCGJTu20g4/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Enroll Custom HOTP Factor

Enrollment via the Authentication API is currently not supported for Custom HOTP Factor. Please refer to the Factors API documentation if you would like to enroll users for this type of Factor.

Activate Factor

POST /api/v1/authn/factors/${factorId}/lifecycle/activate

CORS

The sms,call, and token:software:totp Factor types require activation to complete the enrollment process.

Activate TOTP Factor

Activates a token:software:totp Factor by verifying the OTP

Note: This API implements the TOTP standard, which is used by apps like Okta Verify and Google Authenticator.

Request parameters for activate TOTP Factor
Parameter Description Param Type DataType Required
factorId id of Factor returned from enrollment URL String TRUE
passCode OTP generated by device Body String TRUE
stateToken state token for the current transaction Body String TRUE
Response parameters for activate TOTP Factor

Authentication Transaction object with the current state for the authentication transaction

If the passcode is invalid, you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your passcode doesn't match our records. Please try again."
    }
  ]
}
Activate TOTP request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "passCode": "123456"
}' "https://${yourOktaDomain}/api/v1/authn/factors/ostf1fmaMGJLMNGNLIVG/lifecycle/activate"
Activate TOTP response example
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Activate SMS Factor

Activates an sms Factor by verifying the OTP. The request and response is identical to activating a TOTP Factor

Activate SMS Factor request parameters
Parameter Description Param Type DataType Required
factorId id of Factor returned from enrollment URL String TRUE
passCode OTP sent to mobile device Body String TRUE
stateToken state token for the current transaction Body String TRUE
Activate SMS Factor response parameters

Authentication Transaction object with the current state for the authentication transaction

If the passcode is invalid, you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your passcode doesn't match our records. Please try again."
    }
  ]
}
Activate SMS Factor request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "passCode": "123456"
}' "https://${yourOktaDomain}/api/v1/authn/factors/sms1o51EADOTFXHHBXBP/lifecycle/activate"
Activate SMS Factor response example
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Activate Call Factor

Activates a call Factor by verifying the OTP. The request and response is identical to activating a TOTP Factor

Activate Call Factor request parameters
Parameter Description Param Type DataType Required
factorId id of Factor returned from enrollment URL String TRUE
passCode Passcode received via the voice call Body String TRUE
stateToken state token for the current transaction Body String TRUE
Activate Call Factor response parameters

Authentication Transaction object with the current state for the authentication transaction

If the passcode is invalid, you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your passcode doesn't match our records. Please try again."
    }
  ]
}
Activate Call Factor request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "passCode": "12345"
}' "https://${yourOktaDomain}/api/v1/authn/factors/clf1o51EADOTFXHHBXBP/lifecycle/activate"
Activate Call Factor response example
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Activate Email Factor

Activates an email Factor by verifying the OTP. The request and response are identical to activating a TOTP Factor

Activate Email Factor request parameters
Parameter Description Param Type DataType Required
factorId id of factor returned from enrollment URL String TRUE
passCode Passcode received via the email message Body String TRUE
stateToken state token for the current transaction Body String TRUE
Activate Email Factor response parameters

Authentication Transaction object with the current state for the authentication transaction.

If the passcode is invalid, you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your passcode doesn't match our records. Please try again."
    }
  ]
}
Activate Email Factor request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "passCode": "12345"
}' "https://${yourOktaDomain}/api/v1/authn/factors/emf1o51EADOTFXHHBXBP/lifecycle/activate"
Activate Email Factor response example
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Activate Push Factor

Activation of push factors are asynchronous and must be polled for completion when the factorResult returns a WAITING status.

Activations have a short lifetime (minutes) and TIMEOUT if they are not completed before the expireAt timestamp. Use the published activate link to restart the activation process if the activation is expired.

Activate Push Factor request parameters
Parameter Description Param Type DataType Required
factorId id of Factor returned from enrollment URL String TRUE
stateToken state token for the current transaction Body String TRUE
Activate Push Factor response parameters

Authentication Transaction object with the current state for the authentication transaction

Activate Push Factor request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate"
Activate Push Factor response example (waiting)

Note: Follow the the published next link to keep polling for activation completion.

{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "factorResult": "WAITING",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "_embedded": {
        "activation": {
          "expiresAt": "2015-11-03T10:15:57.000Z",
          "_links": {
            "qrcode": {
              "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/qr/00fukNElRS_Tz6k-CFhg3pH4KO2dj2guhmaapXWbc4",
              "type": "image/png"
            },
            "send": [
              {
                "name": "email",
                "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/email",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              },
              {
                "name": "sms",
                "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/sms",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              }
            ]
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/poll",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Activate Push Factor response example (success)
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}
Activate Push Factor response example (timeout)

Note: Follow the the published activate link to restart the activation process.

{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "factorResult": "TIMEOUT",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "_embedded": {
        "activation": {
          "factorResult": "TIMEOUT",
          "_links": {
            "activate": {
              "href": "https://${yourOktaDomain}/api/v1/users/00u4vi0VX6U816Kl90g4/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate",
              "hints": {
                "allow": [
                  "POST"
                ]
              }
            },
            "send": [
              {
                "name": "email",
                "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/email",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              },
              {
                "name": "sms",
                "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/sms",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              }
            ]
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "activate",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Poll for Push Factor activation

After the push notification is sent to the user's device, we need to know when the user completes the activation. This is done by polling the "poll" link.

Poll for Push request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/poll"
Poll for Push response example
{
  "stateToken":"007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt":"2016-12-22T21:36:47.000Z",
  "status":"MFA_ENROLL_ACTIVATE",
  "factorResult":"WAITING",
  "_embedded":{
    "user":{
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2016-12-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor":{
      "id":"opfh52xcuft3J4uZc0g3",
      "factorType":"push",
      "provider":"OKTA",
      "vendorName":"OKTA",
      "_embedded":{
        "activation":{
          "expiresAt":"2016-12-22T21:41:47.000Z",
          "factorResult":"WAITING",
          "_links":{
            "send":[
              {
                "name":"email",
                "href":"https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/email",
                "hints":{
                  "allow":["POST"]
                }
              },
              {
                "name":"sms",
                "href":"https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/sms",
                "hints":{
                  "allow":["POST"]
                }
              }
            ],
            "qrcode":{
              "href":"https://${yourOktaDomain}/api/v1/users/opfh52xcuft3J4uZc0g3/factors/opfn169oIx3k63Klh0g3/qr/20111huUFWDFTAeq_lFQKfKFS_rLABkE_pKgGl5PBUeLvJVmaIrWq5u",
              "type":"image/png"
            }
          }
        }
      }
    }
  },
  "_links":{
    "next":{
      "name":"poll",
      "href":"https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/poll",
      "hints":{
        "allow":["POST"]
      }
    },
    "cancel":{
      "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints":{
        "allow":["POST"]
      }
    },
    "prev":{
      "href":"https://${yourOktaDomain}/api/v1/authn/previous",
      "hints":{
        "allow":["POST"]
      }
    }
  }
}

Sends an activation email or SMS when the user is unable to scan the QR code provided as part of an Okta Verify transaction. If for any reason the user can't scan the QR code, they can use the link provided in email or SMS to complete the transaction.

Note: The user must click the link from the same device as the one where the Okta Verify app is installed.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/email"
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "profile": {
    "phoneNumber": "+1-555-415-1337"
  }
}' "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/sms"
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_ENROLL_ACTIVATE",
  "factorResult": "WAITING",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "_embedded": {
        "activation": {
          "expiresAt": "2015-11-03T10:15:57.000Z",
          "_links": {
            "qrcode": {
              "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/qr/00fukNElRS_Tz6k-CFhg3pH4KO2dj2guhmaapXWbc4",
              "type": "image/png"
            },
            "send": [
              {
                "name": "email",
                "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/email",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              },
              {
                "name": "sms",
                "href": "https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/sms",
                "hints": {
                  "allow": [
                    "POST"
                  ]
                }
              }
            ]
          }
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/lifecycle/activate/poll",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Activate U2F Factor

Activation gets the registration information from the U2F token using the API and passes it to Okta.

Get registration information from U2F token by calling the U2F Javascript library method
<!-- Get the u2f-api.js from https://github.com/google/u2f-ref-code/tree/master/u2f-gae-demo/war/js -->
<script src="/u2f-api.js"></script>
<script>
  // Use the appId from the activation object
  var appId = activation.appId;

  // Use the version and nonce from the activation object
  var registerRequests = [
    {
      version: activation.version,
      challenge: activation.nonce
    }
  ];

  u2f.register(appId, registerRequests, [], function (data) {
    if (data.errorCode && data.errorCode !== 0) {
      // Error from U2F platform
    } else {
      // Get the registrationData from the callback result
      var registrationData = data.registrationData;

      // Get the clientData from the callback result
      var clientData = data.clientData;
    }
  });
</script>

Activate a u2f Factor by verifying the registration data and client data.

Activate U2F request parameters
Parameter Description Param Type DataType Required
clientData base64-encoded client data from U2F javascript call Body String TRUE
factorId id of Factor returned from enrollment URL String TRUE
registrationData base64-encoded registration data from U2F javascript call Body String TRUE
stateToken state token for the current transaction Body String TRUE
Activate U2F response parameters

Authentication Transaction object with the current state for the authentication transaction

If the registration nonce is invalid or if registration data is invalid, you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your passcode doesn't match our records. Please try again."
    }
  ]
}
Activate U2F request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "registrationData": "BQTl3Iu9V4caCvcI44pmYwIehICWyboL_J2Wl5FA6ZGNx9qT11Df-rHJIy9iP6MSJ_qAaKqdq8O0XVqBG46p6qbpQLIb471thYthrQiW9955tNdORCEhvZX9iYNI1peNlETOr7Qx_PgIZ6Ein6aB3wH9JCTGgsdd4JX3cYixbj1v9W8wggJEMIIBLqADAgECAgRVYr6gMAsGCSqGSIb3DQEBCzAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowKjEoMCYGA1UEAwwfWXViaWNvIFUyRiBFRSBTZXJpYWwgMTQzMjUzNDY4ODBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABEszH3c9gUS5mVy-RYVRfhdYOqR2I2lcvoWsSCyAGfLJuUZ64EWw5m8TGy6jJDyR_aYC4xjz_F2NKnq65yvRQwmjOzA5MCIGCSsGAQQBgsQKAgQVMS4zLjYuMS40LjEuNDE0ODIuMS41MBMGCysGAQQBguUcAgEBBAQDAgUgMAsGCSqGSIb3DQEBCwOCAQEArBbZs262s6m3bXWUs09Z9Pc-28n96yk162tFHKv0HSXT5xYU10cmBMpypXjjI-23YARoXwXn0bm-BdtulED6xc_JMqbK-uhSmXcu2wJ4ICA81BQdPutvaizpnjlXgDJjq6uNbsSAp98IStLLp7fW13yUw-vAsWb5YFfK9f46Yx6iakM3YqNvvs9M9EUJYl_VrxBJqnyLx2iaZlnpr13o8NcsKIJRdMUOBqt_ageQg3ttsyq_3LyoNcu7CQ7x8NmeCGm_6eVnZMQjDmwFdymwEN4OxfnM5MkcKCYhjqgIGruWkVHsFnJa8qjZXneVvKoiepuUQyDEJ2GcqvhU2YKY1zBGAiEAxWDh5F7vr0AoEsi3N-uR6KR3ADXlZnQgzROUTVhff8ICIQCiUUG1FkQ9e8PW1dhRk6tjHjL22KZ9JqBrTfpytC5jaQ==",
  "clientData": "eyAiY2hhbGxlbmdlIjogImFYLS1wMTlibldWcUlnY25HU0hLIiwgIm9yaWdpbiI6ICJodHRwczpcL1wvc25hZ2FuZGxhLm9rdGFwcmV2aWV3LmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmZpbmlzaEVucm9sbG1lbnQiIH0=",
  "stateToken": "00MBkDX0vBddsuU1VnDsa7-qqIOi7g51YLNQEen1hi"
}' "https://${yourOktaDomain}/api/v1/authn/factors/fuf1o51EADOTFXHHBXBP/lifecycle/activate"
Activate U2F response example
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Activate WebAuthn Factor

Activation gets the registration information from the WebAuthn assertion using the API and passes it to Okta.

Get registration information from WebAuthn assertion by calling the WebAuthn Javascript library
<!-- Using CryptoUtil.js from https://github.com/okta/okta-signin-widget/blob/master/src/util/CryptoUtil.js -->
<script>
// Convert activation object's challenge and user id from string to binary
activation.challenge = CryptoUtil.strToBin(activation.challenge);
activation.user.id = CryptoUtil.strToBin(activation.user.id);

// navigator.credentials is a global object on WebAuthn-supported clients, used to access WebAuthn API
navigator.credentials.create({
  publicKey: activation
})
  .then(function (newCredential) {
    // Get attestation and clientData from callback result, convert from binary to string
    var attestation = CryptoUtil.binToStr(newCredential.response.attestationObject);
    var clientData = CryptoUtil.binToStr(newCredential.response.clientDataJSON);
  })
  .fail(function (error) {
    // Error from WebAuthn platform
  });
</script>

Activate a webauthn Factor by verifying the attestation and client data.

Activate WebAuthn request parameters
Parameter Description Param Type DataType Required
attestation base64-encoded attestation from the WebAuthn javascript call Body String TRUE
clientData base64-encoded client data from the WebAuthn javascript call Body String TRUE
factorId id of Factor returned from enrollment URL String TRUE
stateToken state token for the current transaction Body String TRUE
Activate WebAuthn response parameters

Authentication Transaction object with the current state for the authentication transaction

If the attestation nonce is invalid, or if the attestation or client data are invalid, you receive a 403 Forbidden status code with the following error:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YDKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your passcode doesn't match our records. Please try again."
    }
  ]
}
Activate WebAuthn request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "attestation: "o2NmbXRmcGFja2VkZ2F0dFN0bXSiY2FsZyZjc2lnWEgwRgIhAMvf2+dzXlHZN1um38Y8aFzrKvX0k5dt/hnDu9lahbR4AiEAuwtMg3IoaElWMp00QrP/+3Po/6LwXfmYQVfsnsQ+da1oYXV0aERhdGFYxkgb9OHGifjS2dG03qLRqvXrDIRyfGAuc+GzF1z20/eVRV2wvl6tzgACNbzGCmSLCyXx8FUDAEIBvWNHOcE3QDUkDP/HB1kRbrIOoZ1dR874ZaGbMuvaSVHVWN2kfNiO4D+HlAzUEFaqlNi5FPqKw+mF8f0XwdpEBlClAQIDJiABIVgg0a6oo3W0JdYPu6+eBrbr0WyB3uJLI3ODVgDfQnpgafgiWCB4fFo/5iiVrFhB8pNH2tbBtKewyAHuDkRolcCnVaCcmQ==",
  "clientData": "eyJjaGFsbGVuZ2UiOiJVSk5wYW9sVWt0dF9vcEZPNXJMYyIsIm9yaWdpbiI6Imh0dHBzOi8vcmFpbi5va3RhMS5jb20iLCJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIn0=",
  "stateToken": "00eacMXqkf2pG8K3sBbWqTJNStZpEi9-1Bfwl_mfQT"
}' "https://${yourOktaDomain}/api/v1/authn/factors/fwfbaopNw5CCGJTu20g4/lifecycle/activate"
Activate WebAuthn response example
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9pe",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Verify Factor

Verifies an enrolled Factor for an authentication transaction with the MFA_REQUIRED or MFA_CHALLENGE state

Note: If the sign-on (or app sign-on) policy allows remembering the device, then the end user should be prompted to choose whether the current device should be remembered. This helps reduce the number of times the user is prompted for MFA on the current device. The user's choice should be passed to Okta using the request parameter rememberDevice to the verify endpoint. The default value of rememberDevice parameter is false.

Verify Security Question Factor

POST /api/v1/authn/factors/${factorId}/verify

CORS

Verifies an answer to a question Factor

Request parameters for verify Security Question Factor
Parameter Description Param Type DataType Required
answer answer to security question Body String TRUE
factorId id of Factor URL String TRUE
rememberDevice user's decision to remember the device URL Boolean FALSE
stateToken state token for the current transaction Body String TRUE
Response parameters for verify Security Question Factor

Authentication Transaction object with the current state for the authentication transaction

If the answer is invalid you receive a 403 Forbidden status code with the following error:

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your answer doesn't match our records. Please try again."
    }
  ]
}
Request example for verify Security Question Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "answer": "mayonnaise"
}' "https://${yourOktaDomain}/api/v1/authn/factors/ufs1pe3ISGKGPYKXRBKK/verify"
Response example for verify Security Question Factor
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00ZD3Z7ixppspFljXV2t_Z6GfrYzqG7cDJ8reWo2hy",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Verify SMS Factor

POST /api/v1/authn/factors/${factorId}/verify

CORS
Request parameters for verify SMS Factor
Parameter Description Param Type DataType Required
factorId id of Factor URL String TRUE
passCode OTP sent to device Body String FALSE
rememberDevice user's decision to remember the device URL Boolean FALSE
stateToken state token for the current transaction Body String TRUE

Note: If you omit passCode in the request, a new OTP is sent to the device, otherwise the request attempts to verify the passCode.

Response parameters for verify SMS Factor

Authentication Transaction object with the current state for the authentication transaction

If the passCode is invalid, you receive a 403 Forbidden status code with the following error:

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your answer doesn't match our records. Please try again."
    }
  ]
}
Send SMS challenge (OTP)

Omit passCode in the request to send an OTP to the device.

Request example for send SMS challenge (OTP)
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/sms193zUBEROPBNZKPPE/verify"
Response example for send SMS challenge (OTP)
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_CHALLENGE",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "sms193zUBEROPBNZKPPE",
      "factorType": "sms",
      "provider": "OKTA",
      "profile": {
        "phoneNumber": "+1 XXX-XXX-1337"
      }
    }
  },
  "_links": {
    "next": {
      "name": "verify",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/sms193zUBEROPBNZKPPE/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "sms",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/sms193zUBEROPBNZKPPE/verify/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}
Resend SMS challenge

Use the resend link to send another OTP if the user doesn't receive the original SMS OTP.

Notes: The current rate limit is one SMS challenge per device every 30 seconds.

Okta round-robins between SMS providers with every resend request to help ensure delivery of SMS OTP across different carriers.

Request example for resend SMS
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/sms193zUBEROPBNZKPPE/verify/resend"
Verify SMS challenge (OTP)

Specify passCode in the request to verify the Factor.

Request example for verify SMS challenge (OTP)
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "passCode": "657866"
}' "https://${yourOktaDomain}/api/v1/authn/factors/sms193zUBEROPBNZKPPE/verify"
Response example for verify SMS challenge (OTP)
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00t6IUQiVbWpMLgtmwSjMFzqykb5QcaBNtveiWlGeM",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Verify Call Factor

POST /api/v1/authn/factors/${factorId}/verify

CORS
Request parameters for verify Call Factor
Parameter Description Param Type DataType Required
factorId id of Factor URL String TRUE
passCode OTP sent to device Body String FALSE
rememberDevice user's decision to remember the device URL Boolean FALSE
stateToken state token for the current transaction Body String TRUE

Note: If you omit passCode in the request, a new OTP is sent to the device, otherwise the request attempts to verify the passCode.

Response parameters for verify Call Factor

Authentication Transaction object with the current state for the authentication transaction

If the passCode is invalid, you receive a 403 Forbidden status code with the following error:

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your answer doesn't match our records. Please try again."
    }
  ]
}
Send Voice Call challenge (OTP)

Omit passCode in the request to send an OTP to the device.

Request example for send Voice Call challenge (OTP)
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/clf193zUBEROPBNZKPPE/verify"
Response example for send Voice Call challenge (OTP)
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_CHALLENGE",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factor": {
      "id": "clf193zUBEROPBNZKPPE",
      "factorType": "call",
      "provider": "OKTA",
      "profile": {
        "phoneNumber": "+1 XXX-XXX-1337"
      }
    }
  },
  "_links": {
    "next": {
      "name": "verify",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/clf193zUBEROPBNZKPPE/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}
Resend voice call challenge

Use the resend link to send another OTP if the user doesn't receive the original Voice Call OTP.

Notes: The current rate limit is one voice call challenge per device every 30 seconds.

Okta round-robins between voice call providers with every resend request to help ensure delivery of voice call OTP across different carriers.

Request example for resend voice call
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/clf193zUBEROPBNZKPPE/verify/resend"
Verify Call challenge (OTP)

Specify passCode in the request to verify the Factor.

Request example for verify Call challenge
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "passCode": "65786"
}' "https://${yourOktaDomain}/api/v1/authn/factors/clf193zUBEROPBNZKPPE/verify"
Response example for verify Call challenge
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00t6IUQiVbWpMLgtmwSjMFzqykb5QcaBNtveiWlGeM",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Verify TOTP Factor

POST /api/v1/authn/factors/${factorId}/verify

CORS

Verifies an OTP for a token:software:totp or token:hotp Factor

Note: This API implements the TOTP standard, which is used by apps like Okta Verify and Google Authenticator.

Request parameters for verify TOTP Factor
Parameter Description Param Type DataType Required
factorId id of Factor URL String TRUE
passCode OTP sent to device Body String FALSE
rememberDevice user's decision to remember the device URL Boolean FALSE
stateToken state token for the current transaction Body String TRUE
Response parameters for verify TOTP Factor

Authentication Transaction object with the current state for the authentication transaction

If the passcode is invalid, you receive a 403 Forbidden status code with the following error:

{
  "errorCode": "E0000068",
  "errorSummary": "Invalid Passcode/Answer",
  "errorLink": "E0000068",
  "errorId": "oaei_IfXcpnTHit_YEKGInpFw",
  "errorCauses": [
    {
      "errorSummary": "Your passcode doesn't match our records. Please try again."
    }
  ]
}
Request example for verify TOTP Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "passCode": "657866"
}' "https://${yourOktaDomain}/api/v1/authn/factors/ostfm3hPNYSOIOIVTQWY/verify"
Response example for verify TOTP Factor
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00t6IUQiVbWpMLgtmwSjMFzqykb5QcaBNtveiWlGeM",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}

Verify Push Factor

POST /api/v1/authn/factors/${factorId}/verify

CORS

Sends an asynchronous push notification (challenge) to the device for the user to approve or reject. The factorResult for the transaction has a result of WAITING, SUCCESS, REJECTED, or TIMEOUT.

Request parameters for verify Push Factor
Parameter Description Param Type DataType Required
autoPush user's decision to send a push to the device automatically URL Boolean FALSE
factorId id of Factor URL String TRUE
rememberDevice user's decision to remember the device URL Boolean FALSE
stateToken state token for the current transaction Body String TRUE

Okta Verify Push details pertaining to auto-push

  • You don't need to pass the autoPush flag to Okta unless you have a custom sign-in flow that doesn't use the Okta Sign-In Widget, but want Okta to keep track of this preference. The custom sign-in flow must still handle the logic to actually send the Auto-Push, since this param only deals with the Auto-Push setting.
  • If you pass the autoPush query param when verifying an Okta Verify Push Factor, Okta saves this value as the user's preference to have the push notification sent automatically if the verification is successful (the user taps Approve on their phone).
  • If there is already a saved Auto-Push preference, the successful verify call overrides the current preference if it is different from the value of autoPush.
  • This saved Auto-Push preference is always returned in the /api/v1/authn/ response's autoPushEnabled field if the user is enrolled for the Okta Verify Push Factor example here. If the user's Auto-Push preference hasn't explicitly been set before, autoPushEnabled has a value of false.
  • The Auto-Push preference is stored in a cookie value and users that clear their cookies remove that preference.
  • Please note, the autoPush flag has no effect when trying to verify a Factor other than Okta Verify Push (factorId prefix = "opf").
Request example for verify Push Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/ufs1pe3ISGKGPYKXRBKK/verify"
Response example (waiting)

Note: Keep polling authentication transactions with WAITING result until the challenge completes or expires.

{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_CHALLENGE",
  "factorResult": "WAITING",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {
        "deviceType": "SmartPhone_IPhone",
        "name": "Gibson",
        "platform": "IOS",
        "version": "9.0"
      }
    }
  },
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "push",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}
Response example (waiting for 3-number verification challenge response)

Note: If Okta detects an unusual sign-in attempt, the end user will receive a 3-number verification challenge and the correct answer of the challenge will be provided in the polling response. This is similar to the standard waiting response but with the addition of a correctAnswer property in the challenge object. The correctAnswer property will only be included in the response if the end user is on the 3-number verification challenge view in the Okta Verify mobile app. Look at Sign in to your org with Okta Verify for more details about this challenge flow.

{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_CHALLENGE",
  "factorResult": "WAITING",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {
        "deviceType": "SmartPhone_IPhone",
        "name": "Gibson",
        "platform": "IOS",
        "version": "9.0"
      },
      "_embedded": {
        "challenge": {
          "correctAnswer": 92
        }
      }
    }
  },
  "_links": {
    "next": {
      "name": "poll",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "push",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}
Response example (approved)
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "SUCCESS",
  "sessionToken": "00Fpzf4en68pCXTsMjcX8JPMctzN2Wiw4LDOBL_9xx",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  }
}
Response example (rejected)
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_CHALLENGE",
  "factorResult": "REJECTED",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {
        "deviceType": "SmartPhone_IPhone",
        "name": "Gibson",
        "platform": "IOS",
        "version": "9.0"
      }
    }
  },
  "_links": {
    "next": {
      "name": "verify",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "push",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}
Response example (timeout)
{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "MFA_CHALLENGE",
  "factorResult": "TIMEOUT",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    },
    "factors": {
      "id": "opfh52xcuft3J4uZc0g3",
      "factorType": "push",
      "provider": "OKTA",
      "profile": {
        "deviceType": "SmartPhone_IPhone",
        "name": "Gibson",
        "platform": "IOS",
        "version": "9.0"
      }
    }
  },
  "_links": {
    "next": {
      "name": "verify",
      "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "prev": {
      "href": "https://${yourOktaDomain}/api/v1/authn/previous",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": [
      {
        "name": "push",
        "href": "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify/resend",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    ]
  }
}
Resend push notification

Use the resend link to send another push notification if the user didn't receive the previous one due to timeout or error.

Request example for resend push notification
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb"
}' "https://${yourOktaDomain}/api/v1/authn/factors/opfh52xcuft3J4uZc0g3/verify/resend"

Verify Duo Factor

Verification of the Duo Factor is implemented as an integration with Duo widget. The process is very similar to the enrollment where the widget is embedded in an iframe - "duo_iframe". Verification starts with request to the Okta API, then continues with a Duo widget that handles the actual verification. We need to pass the state token as hidden object in "duo_form". The authentication completes with call to poll link to verify the state and obtain session token.

Request example for verify Duo Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "${stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors/${factorId}/verify"
Response example for verify Duo Factor
{
    "stateToken":"00CzoxFVe4R2nv0hTxm32r1kayfrrOkuxcE2rfINwZ",
    "expiresAt":"2016-07-13T14:13:58.000Z",
    "status":"MFA_CHALLENGE",
    "factorResult":"WAITING",
    "_embedded":{
        "user":{
            "id":"00ukv3jVTgRjDctlX0g3",
            "passwordChanged":"2016-07-13T13:29:58.000Z",
            "profile":{
                "login":"first.last@gexample.com",
                "firstName":"First",
                "lastName":"Last",
                "locale":"en_US",
                "timeZone":"America/Los_Angeles"
            }
        },
        "factor":{
            "id":"dsflnpo99zpfMyaij0g3",
            "factorType":"web",
            "provider":"DUO",
            "vendorName":"DUO",
            "profile":{
                "credentialId":"first.last@example.com"
            },
            "_embedded":{
                "verification":{
                    "host":"api-your-host.duosecurity.com",
                    "signature":"TX|...your-signature",
                    "factorResult":"WAITING",
                    "_links":{
                        "complete":{
                            "href":"https://${yourOktaDomain}/api/v1/authn/factors/dsflnpo99zpfMyaij0g3/lifecycle/duoCallback",
                            "hints":{
                                "allow":[
                                    "POST"
                                ]
                            }
                        },
                        "script":{
                            "href":"https://${yourOktaDomain}/js/sections/duo/Duo-Web-v2.js",
                            "type":"text/javascript; charset=utf-8"
                        }
                    }
                }
            }
        },
        "policy":{
            "allowRememberDevice":true,
            "rememberDeviceLifetimeInMinutes":15,
            "rememberDeviceByDefault":false
        }
    },
    "_links":{
        "next":{
            "name":"poll",
            "href":"https://${yourOktaDomain}/api/v1/authn/factors/dsflnpo99zpfMyaij0g3/verify",
            "hints":{
                "allow":[
                    "POST"
                ]
            }
        },
        "cancel":{
            "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
            "hints":{
                "allow":[
                    "POST"
                ]
            }
        },
        "prev":{
            "href":"https://${yourOktaDomain}/api/v1/authn/previous",
            "hints":{
                "allow":[
                    "POST"
                ]
            }
        }
    }
}
Sample for Duo iFrame
...
<!--
    The Duo SDK will automatically bind to this iFrame and populate it for us.
    See https://www.duosecurity.com/docs/duoweb for more info.
 -->
<iframe id="duo_iframe" width="620" height="330" frameborder="0"></iframe>
<!--
    The Duo SDK will automatically bind to this form and submit it for us.
    See https://www.duosecurity.com/docs/duoweb for more info.
 -->
<form method="POST" id="duo_form">
    <!-- The state token is required here (in order to bind anonymous request back into Auth API) -->
    <input type="hidden" name="stateToken" value='00CzoxFVe4R2nv0hTxm32r1kayfrrOkuxcE2rfINwZ' />
</form>

<script src="https://${yourOktaDomain}/js/sections/duo/Duo-Web-v2.js"></script>

<!-- The host, sig_request, and post_action values will be given via the Auth API -->
<script>
    Duo.init({
        'host': 'api-your-host.duosecurity.com',
        'sig_request': 'TX|...your-signature',
        'post_action': 'https://${yourOktaDomain}/api/v1/authn/factors/dsflnpo99zpfMyaij0g3/lifecycle/duoCallback'
    });
</script>
...

Verification poll request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "${stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors/${factorId}/verify"
Verification poll response example
{
    "expiresAt":"2016-07-13T14:14:44.000Z",
    "status":"SUCCESS",
    "sessionToken":"201111XUk7La2gw5r5PV1IhU4WSd0fV6mvNYdlJoeqjuyej7S83x3Hr",
    "_embedded":{
        "user":{
            "id":"00ukv3jVTgRjDctlX0g3",
            "passwordChanged":"2016-07-13T13:29:58.000Z",
            "profile":{
                "login":"first.last@example.com",
                "firstName":"First",
                "lastName":"Last",
                "locale":"en_US",
                "timeZone":"America/Los_Angeles"
            }
        }
    }
}

Verify U2F fFactor

POST /api/v1/authn/factors/${factorId}/verify

CORS

Note: The appId property in Okta U2F enroll/verify API response is the origin of the web page that triggers the API request (assuming the origin has been configured to be trusted by Okta). According to FIDO spec, enroll and verify U2F device with appIds in different DNS zone is not allowed. For example, if a user enrolled a U2F device via Okta Sign-in widget that is hosted at https://login.company.com, while the user can verify the U2F Factor from https://login.company.com, the user would not be able to verify it from Okta portal https://company.okta.com, U2F device would return error code 4 - DEVICE_INELIGIBLE.

Start verification to get challenge nonce

Verification of the U2F Factor starts with getting the challenge nonce and U2F token details and then using the client-side JavaScript API to get the signed assertion from the U2F token.

Request example for verify U2F Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "${stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors/${factorId}/verify"
Response example for verify U2F Factor
{
   "stateToken":"00wCfuPA3qX3azDawSdPGFIhHuzbZX72Gv4bu_ew9d",
   "expiresAt":"2016-12-06T01:32:39.000Z",
   "status":"MFA_CHALLENGE",
   "_embedded":{
      "user":{
         "id":"00u21eb3qyRDNNIKTGCW",
         "passwordChanged":"2015-10-28T23:27:57.000Z",
         "profile":{
            "login":"first.last@gmail.com",
            "firstName":"First",
            "lastName":"Last",
            "locale":"en",
            "timeZone":"America/Los_Angeles"
         }
      },
      "factor":{
         "id":"fuf8y2l4n5mfH0UWe0h7",
         "factorType":"u2f",
         "provider":"FIDO",
         "vendorName":"FIDO",
         "profile":{
            "credentialId":"shvjvW2Fi2GtCJb33nm0105EISG9lf2Jg0jWl42URM6vtDH8-AhnoSKfpoHfAf0kJMaCx13glfdxiLFuPW_1bw",
            "appId":"https://${yourOktaDomain}",
            "version":"U2F_V2"
         },
         "_embedded":{
            "challenge":{
               "nonce":"tT1MI7XGzMu48Ivnz3vB",
               "timeoutSeconds":20
            }
         }
      },
      "policy":{
         "allowRememberDevice":true,
         "rememberDeviceLifetimeInMinutes":0,
         "rememberDeviceByDefault":false
      }
   },
   "_links":{
      "next":{
         "name":"verify",
         "href":"https://${yourOktaDomain}/api/v1/authn/factors/fuf8y2l4n5mfH0UWe0h7/verify",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      },
      "cancel":{
         "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      },
      "prev":{
         "href":"https://${yourOktaDomain}/api/v1/authn/previous",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      }
   }
}
Get the signed assertion from the U2F token
<!-- Get the u2f-api.js from https://github.com/google/u2f-ref-code/tree/master/u2f-gae-demo/war/js -->
<script src="/u2f-api.js"></script>
<script>
  // Use the nonce from the challenge object
  var challengeNonce = factor._embedded.challenge.nonce;

  // Use the appId from factor profile object
  var appId = factor.profile.appId;

  // Use the version and credentialId from factor profile object
  var registeredKeys = [
    {
      version: factor.profile.version,
      keyHandle: factor.profile.credentialId
    }
  ];

  // Call the U2F javascript API to get signed assertion from the U2F token
  u2f.sign(appId, factorData.challenge.nonce, registeredKeys, function (data) {
    if (data.errorCode && data.errorCode !== 0) {
      // Error from U2F platform
    } else {
      // Get the client data from callback result
      var clientData = data.clientData;

      // Get the signature data from callback result
      var signatureData = data.signatureData;
    }
  });
</script>
Post the signed assertion to Okta to complete verification
Request parameters for verify U2F Factor
Parameter Description Param Type DataType Required
clientData base64-encoded client data from the U2F token Body String TRUE
factorId id of Factor URL String TRUE
rememberDevice user's decision to remember the device URL Boolean FALSE
signatureData base64-encoded signature data from the U2F token Body String TRUE
stateToken state token for the current transaction Body String TRUE
Request example for signed assertion
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "${stateToken}",
  "clientData":"eyAiY2hhbGxlbmdlIjogIlJ6ZDhQbEJEWUEyQ0VsbXVGcHlMIiwgIm9yaWdpbiI6ICJodHRwczpcL1wvc25hZ2FuZGxhLm9rdGFwcmV2aWV3LmNvbSIsICJ0eXAiOiAibmF2aWdhdG9yLmlkLmdldEFzc2VydGlvbiIgfQ==",
  "signatureData":"AQAAAAEwRQIgRDEdmXr_jh1bEHtoUs1l7mMd-eUDO0eKqXKkrK5hUi0CIQDaVX030GgxVPr4RX3c4XgugildmHwDLwKRL0aMS3Sbpw=="
}' "https://${yourOktaDomain}/api/v1/authn/factors/${factorId}/verify"
Response of U2F verification example
{
    "expiresAt":"2016-07-13T14:14:44.000Z",
    "status":"SUCCESS",
    "sessionToken":"201111XUk7La2gw5r5PV1IhU4WSd0fV6mvNYdlJoeqjuyej7S83x3Hr",
    "_embedded":{
        "user":{
            "id":"00ukv3jVTgRjDctlX0g3",
            "passwordChanged":"2016-07-13T13:29:58.000Z",
            "profile":{
                "login":"first.last@example.com",
                "firstName":"First",
                "lastName":"Last",
                "locale":"en_US",
                "timeZone":"America/Los_Angeles"
            }
        }
    }
}

Verify WebAuthn Factor

POST /api/v1/authn/factors/${factorIdOrFactorType}/verify

CORS

Verifies a user with a WebAuthn Factor. The verification process starts with getting the WebAuthn credential request options, which are used to help select an appropriate authenticator using the WebAuthn API. This authenticator then generates an assertion that may be used to verify the user.

Note: a factorId or factorType may be specified for WebAuthn's verify endpoint, as the WebAuthn Factor type supports multiple Factor instances. When a factorId is used, the verification procedure is no different from any other factors, with verification for a specific Factor instance. When "webauthn" (the factorType name for WebAuthn) is used, verification would be acceptable with any WebAuthn Factor instance enrolled for the user.

Start verification to get challenge nonce

Verification of the WebAuthn Factor starts with getting the WebAuthn credential request details (including the challenge nonce) then using the client-side JavaScript API to get the signed assertion from the WebAuthn authenticator.

For more information about these credential request options, see the WebAuthn spec for PublicKeyCredentialRequestOptions.

Request example for verify WebAuthn Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "stateToken": "${stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors/${factorIdOrFactorType}/verify"
Response example for verify WebAuthn Factor by factorId
{
   "stateToken":"00lbJNfhlFVRVAR37O3PRzNFkx-v5kgMYHJPTtMDS2",
   "expiresAt":"2019-10-24T00:21:05.000Z",
   "status":"MFA_CHALLENGE",
   "factorResult":"CHALLENGE",
   "challengeType":"FACTOR",
   "_embedded":{
      "user":{
         "id":"00u21eb3qyRDNNIKTGCW",
         "passwordChanged":"2015-10-28T23:27:57.000Z",
         "profile":{
            "login":"first.last@gmail.com",
            "firstName":"First",
            "lastName":"Last",
            "locale":"en",
            "timeZone":"America/Los_Angeles"
         }
      },
      "factor":{
         "id":"fwfbaopNw5CCGJTu20g4",
         "factorType":"webauthn",
         "provider":"FIDO",
         "vendorName":"FIDO",
         "profile":{
            "credentialId":"AZBXkiL5GrhfSvLeS4MHSvTVC_1ZLPcwI4SKKqKF1sd9TL_UFoQliUKu00to6slexSOZ9oh1h54BbTXPA343qHBF",
            "authenticatorName":"MacBook Touch ID"
         },
         "_embedded":{
            "challenge":{
               "challenge":"K0UNqWlz2TCCDd5qEkBf",
               "extensions":{
               }
            }
         }
      },
      "policy":{
         "allowRememberDevice":false,
         "rememberDeviceLifetimeInMinutes":0,
         "rememberDeviceByDefault":false,
         "factorsPolicyInfo":{

         }
      }
   },
   "_links":{
      "next":{
         "name":"verify",
         "href":"https://${yourOktaDomain}/api/v1/authn/factors/fwfbaopNw5CCGJTu20g4/verify",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      },
      "prev":{
         "href":"https://${yourOktaDomain}/api/v1/authn/previous",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      },
      "cancel":{
         "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
         "hints":{
            "allow":[
               "POST"
            ]
         }
      }
   }
}
Response example for verify WebAuthn Factor by factorType
{
  "stateToken":"00lbJNfhlFVRVAR37O3PRzNFkx-v5kgMYHJPTtMDS2",
  "expiresAt":"2019-10-24T00:21:05.000Z",
  "status":"MFA_CHALLENGE",
  "factorResult":"CHALLENGE",
  "challengeType":"FACTOR_TYPE",
  "factorType":"webauthn",
  "_embedded":{
    "user":{
      "id":"00u21eb3qyRDNNIKTGCW",
      "passwordChanged":"2015-10-28T23:27:57.000Z",
      "profile":{
        "login":"first.last@gmail.com",
        "firstName":"First",
        "lastName":"Last",
        "locale":"en",
        "timeZone":"America/Los_Angeles"
      }
    },
    "challenge":{
      "challenge":"K0UNqWlz2TCCDd5qEkBf",
      "extensions":{

      }
    },
    "factors":[
      {
        "id":"fwfbaopNw5CCGJTu20g4",
        "factorType":"webauthn",
        "provider":"FIDO",
        "vendorName":"FIDO",
        "profile":{
          "credentialId":"AZBXkiL5GrhfSvLeS4MHSvTVC_1ZLPcwI4SKKqKF1sd9TL_UFoQliUKu00to6slexSOZ9oh1h54BbTXPA343qHBF",
          "authenticatorName":"MacBook Touch ID"
        }
      },
      {
        "id":"fwfbadoFkIGXCH8ky0g4",
        "factorType":"webauthn",
        "provider":"FIDO",
        "vendorName":"FIDO",
        "profile":{
          "credentialId":"5V1tI15ifCWhZSLvv9szL4HjRk-vpBYYg86n4LZlVg5bAg2_UnP-vjc4ix60Uh9ehLluB7KsMzmEU7y_TuRaJA",
          "authenticatorName":"Yubikey 5"
        }
      }
    ],
    "policy":{
      "allowRememberDevice":false,
      "rememberDeviceLifetimeInMinutes":0,
      "rememberDeviceByDefault":false,
      "factorsPolicyInfo":{

      }
    }
  },
  "_links":{
    "next":{
      "name":"verify",
      "href":"https://${yourOktaDomain}/api/v1/authn/factors/webauthn/verify",
      "hints":{
        "allow":[
          "POST"
        ]
      }
    },
    "prev":{
      "href":"https://${yourOktaDomain}/api/v1/authn/previous",
      "hints":{
        "allow":[
          "POST"
        ]
      }
    },
    "cancel":{
      "href":"https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints":{
        "allow":[
          "POST"
        ]
      }
    }
  }
}
Get the signed assertion from the WebAuthn authenticator
<!-- Using CryptoUtil.js from https://github.com/okta/okta-signin-widget/blob/master/src/util/CryptoUtil.js -->
<script>
  // For factorId verification, convert activation object's challenge nonce from string to binary
  factor._embedded.challenge.challenge = CryptoUtil.strToBin(factor._embedded.challenge.challenge);

  // For factorType verification, the challenge nonce would be stored in challenge.challenge instead

  // Call the WebAuthn javascript API to get signed assertion from the WebAuthn authenticator
  navigator.credentials.get({
    publicKey: factor._embedded.challenge
  })
    .then(function (assertion) {
      // Get the client data, authenticator data, and signature data from callback result, convert from binary to string
      var clientData = CryptoUtil.binToStr(assertion.response.clientDataJSON);
      var authenticatorData = CryptoUtil.binToStr(assertion.response.authenticatorData);
      var signatureData = CryptoUtil.binToStr(assertion.response.signature);
    })
    .fail(function (error) {
      // Error from WebAuthn platform
    });
</script>
Post the signed assertion to Okta to complete verification
Request parameters for verify WebAuthn Factor
Parameter Description Param Type DataType Required
authenticatorData base64-encoded authenticator data from the WebAuthn authenticator Body String TRUE
clientData base64-encoded client data from the WebAuthn authenticator Body String TRUE
factorId id of Factor URL String TRUE (factorId OR factorType required)
factorType factorType of Factor; for WebAuthn, it is webauthn URL String TRUE (factorId OR factorType required)
rememberDevice user's decision to remember the device URL Boolean FALSE
signatureData base64-encoded signature data from the WebAuthn authenticator Body String TRUE
stateToken state token for the current transaction Body String TRUE
Request example for signed assertion
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "clientData": "eyJjaGFsbGVuZ2UiOiJoOVhzT2JrWmRnNU9vTTdyUS0zMSIsIm9yaWdpbiI6Imh0dHBzOi8vcmFpbi5va3RhMS5jb20iLCJ0eXBlIjoid2ViYXV0aG4uZ2V0In0=",
  "authenticatorData": "SBv04caJ+NLZ0bTeotGq9esMhHJ8YC5z4bMXXPbT95UFXbDsOg==",
  "signatureData": "MEQCICeN9Y3Jw9y1vS1ADghTW5gUKy1JFZpESHXyTRbfjXXrAiAtQLyEjXtkZnZCgnmZA1EjPiHjhvXzkWn83zHtVgGkPQ==",
  "stateToken": "${stateToken}"
}' "https://${yourOktaDomain}/api/v1/authn/factors/${factorIdOrFactorType}/verify"
Response of WebAuthn verification example
{
    "expiresAt":"2016-07-13T14:14:44.000Z",
    "status":"SUCCESS",
    "sessionToken":"201111XUk7La2gw5r5PV1IhU4WSd0fV6mvNYdlJoeqjuyej7S83x3Hr",
    "_embedded":{
        "user":{
            "id":"00ukv3jVTgRjDctlX0g3",
            "passwordChanged":"2016-07-13T13:29:58.000Z",
            "profile":{
                "login":"first.last@example.com",
                "firstName":"First",
                "lastName":"Last",
                "locale":"en_US",
                "timeZone":"America/Los_Angeles"
            }
        }
    }
}

Recovery operations

Forgot password

POST /api/v1/authn/recovery/password

Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user's password

Note: Self-service password reset (forgot password) must be permitted via the user's assigned password policy to use this operation.

Request parameters for forgot password
Parameter Description Param Type DataType Required MaxLength
factorType Recovery Factor to use for primary authentication Body EMAIL or SMS or CALL FALSE
username User's non-qualified short-name (for example: dade.murphy) or unique fully-qualified sign-in name (for example: dade.murphy@example.com) Body String TRUE

Note: A valid factorType is required for requests without an API token with administrator privileges. For more information, see Forgot Password with Trusted Application.

The response is different, depending on whether the request is for a public application or a trusted application.

Response parameters for public application for forgot password

The Recovery Transaction object with RECOVERY_CHALLENGE status for the new recovery transaction

You will always receive a Recovery Transaction response even if the requested username is not a valid identifier to prevent information disclosure.

Response parameters for trusted application for forgot password

The Recovery Transaction object with an issued recoveryToken that can be distributed to the end user

You will receive a 403 Forbidden status code if the username requested is not valid.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "errorCode": "E0000095",
    "errorSummary": "Recovery not allowed for unknown user.",
    "errorLink": "E0000095",
    "errorId": "oaetVarN2dKS6ap08dq0k4n7A",
    "errorCauses": []
}

Forgot password with Email Factor

Starts a new password recovery transaction for the email Factor:

  • You must specify a user identifier (username) but no password in the request.
  • If the request is successful, Okta sends a recovery email asynchronously to the user's primary and secondary email address with a recovery token so the user can complete the transaction.

Primary authentication of a user's recovery credential (for example: EMAIL or SMS) hasn't completed when this request is sent. The user is pending validation.

Okta provides security in the following ways:

  • Since the recovery email is distributed out-of-band and may be viewed on a different user agent or device, this operation does not return a state token and does not have a next link.
  • Okta doesn't publish additional metadata about the user until primary authentication has successfully completed. See the Response Example in this section for details.
Request example for forgot password with Email Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "username": "dade.murphy@example.com",
  "factorType": "EMAIL",
}' "https://${yourOktaDomain}/api/v1/authn/recovery/password"
Response example for forgot password with Email Factor
{
  "status": "RECOVERY_CHALLENGE",
  "factorResult": "WAITING",
  "factorType": "EMAIL",
  "recoveryType": "PASSWORD"
}

Forgot password with SMS Factor

Starts a new password recovery transaction with a user identifier (username) and asynchronously sends a SMS OTP (challenge) to the user's mobile phone. This operation will transition the recovery transaction to the RECOVERY_CHALLENGE state and wait for the user to verify the OTP.

Note: Primary authentication of a user's recovery credential (for example: email or SMS) hasn't yet completed. Okta doesn't publish additional metadata about the user until primary authentication has successfully completed.

Note: SMS recovery Factor must be enabled via the user's assigned password policy to use this operation.

Request example for forgot password with SMS Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "username": "dade.murphy@example.com",
  "factorType": "SMS",
}' "https://${yourOktaDomain}/api/v1/authn/recovery/password"
Response example for forgot password with SMS Factor
{
  "stateToken": "00xdqXOE5qDXX8-PBR1bYv8AESqIEinDy3yul01tyh",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "RECOVERY_CHALLENGE",
  "factorType": "SMS",
  "recoveryType": "PASSWORD",
  "_links": {
    "next": {
      "name": "verify",
      "href": "https://${yourOktaDomain}/api/v1/authn/recovery/factors/SMS/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": {
      "name": "sms",
      "href": "https://${yourOktaDomain}/api/v1/authn/recovery/factors/SMS/resend",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Forgot password with Call Factor

Starts a new password recovery transaction with a user identifier (username) and asynchronously sends a Voice Call with OTP (challenge) to the user's phone. This operation transitions the recovery transaction to the RECOVERY_CHALLENGE state and wait for user to verify the OTP.

Notes:

  • Primary authentication of a user's recovery credential (for example: email or SMS or Voice Call) hasn't yet completed.
  • Okta won't publish additional metadata about the user until primary authentication has successfully completed.
  • Voice Call recovery Factor must be enabled via the user's assigned password policy to use this operation.
Request example for forgot password with Call Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "username": "dade.murphy@example.com",
  "factorType": "call",
}' "https://${yourOktaDomain}/api/v1/authn/recovery/password"
Response example for forgot password with Call Factor
{
  "stateToken": "00xdqXOE5qDXX8-PBR1bYv8AESqIEinDy3yul01tyh",
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "RECOVERY_CHALLENGE",
  "factorType": "call",
  "recoveryType": "PASSWORD",
  "_links": {
    "next": {
      "name": "verify",
      "href": "https://${yourOktaDomain}/api/v1/authn/recovery/factors/CALL/verify",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "resend": {
      "name": "call",
      "href": "https://${yourOktaDomain}/api/v1/authn/recovery/factors/CALL/resend",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Forgot password with trusted application

Allows a trusted application such as an external portal to implement its own primary authentication process and directly obtain a recovery token for a user given just the user's identifier

Note: Directly obtaining a recoveryToken is a highly privileged operation that requires an administrator API token and should be restricted to trusted web applications. Anyone that obtains a recoveryToken for a user and knows the answer to a user's recovery question can reset their password or unlock their account.

Note: The public IP address of your trusted application must be whitelisted as a gateway IP address to forward the user agent's original IP address with the X-Forwarded-For HTTP header.

Request example for forgot password with trusted application
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36" \
-H "X-Forwarded-For: 23.235.46.133" \
-d '{
  "username": "dade.murphy@example.com",
}' "https://${yourOktaDomain}/api/v1/authn/recovery/password"
Response example for forgot password with tusted application
{
  "expiresAt": "2015-11-03T10:15:57.000Z",
  "status": "RECOVERY",
  "recoveryToken": "VBQ0gwBp5LyJJFdbmWCM",
  "recoveryType": "PASSWORD",
  "_embedded": {
    "user": {
      "id": "00ub0oNGTSWTBKOLGLNR",
      "passwordChanged": "2015-09-08T20:14:45.000Z",
      "profile": {
        "login": "dade.murphy@example.com",
        "firstName": "Dade",
        "lastName": "Murphy",
        "locale": "en_US",
        "timeZone": "America/Los_Angeles"
      }
    }
  },
  "_links": {
    "next": {
      "name": "recovery",
      "href": "https://${yourOktaDomain}/api/v1/authn/recovery/token",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://${yourOktaDomain}/api/v1/authn/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Unlock account

POST /api/v1/authn/recovery/unlock

Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user's account

Note: Self-service unlock must be permitted via the user's assigned password policy to use this operation.

Request parameters for unlock account
Parameter Description Param Type DataType Required Max Length
factorType Recovery Factor to use for primary authentication Body EMAIL or SMS FALSE
username User's non-qualified short-name (for example: dade.murphy) or unique fully-qualified sign-in name (for example: dade.murphy@example.com) Body String TRUE

Note: A valid factorType is required for requests without an API token with administrator privileges. (See Unlock Account with Trusted Application).

Response parameter public application for unlock account

Recovery Transaction object with RECOVERY_CHALLENGE status for the new recovery transaction

You always receive a Recovery Transaction response, even if the requested username isn't a valid identifier to prevent information disclosure.

Response parameter trusted application for unlock account

Recovery Transaction object with an issued recoveryToken that can be distributed to the end user

You receive a 403 Forbidden status code if the username requested is not valid.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "errorCode": "E0000095",
    "errorSummary": "Recovery not allowed for unknown user.",
    "errorLink": "E0000095",
    "errorId": "oaetVarN2dKS6ap08dq0k4n7A",
    "errorCauses": []
}

Unlock account with Email Factor

Starts a new unlock recovery transaction with a user identifier (username) and asynchronously sends a recovery email to the user's primary and secondary email address with a recovery token that can be used to complete the transaction

Since the recovery email is distributed out-of-band and may be viewed on a different user agent or device, this operation does not return a state token and does not have a next link.

Notes:

  • Primary authentication of a user's recovery credential (e.g EMAIL or SMS) hasn't yet completed.
  • Okta will not publish additional metadata about the user until primary authentication has successfully completed.
Request example for Email Factor
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "username": "dade.murphy@example.com",
  "factorType": "EMAIL",
}' "https://${yourOktaDomain}/api/v1/authn/recovery/unlock"
Response example for Email Factor
{
  "status": "RECOVERY_CHALLENGE",
  "factorResult": "WAITING",
  "factorType": "EMAIL",
  "recoveryType": "UNLOCK"
}

Unlock account with SMS Factor

Starts a new unlock recovery transaction with a user identifier (username) and asynchronously sends an SMS OTP (challenge) to the user's mobile phone. This operation transitions the recovery transaction to the RECOVERY_CHALLENGE state and waits for the user to verify the OTP.

Notes:

  • Primary authentication of a user's recovery credential (e.g email or SMS) hasn't yet completed.
  • Okta won't publish additional metadata about the user until primary authentication has successfully completed.
  • SMS recovery Factor must be enabled via the user's assigned password policy to use this operation.
Request example for unlock account with SMS Factor