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 (opens new window) to obtain an Okta session cookie and access apps within Okta.

    Note: This is a Classic Engine API. Before you upgrade to Identity Engine, identify your Okta authentication integrations and customizations to find every caller of this API in your org.

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

    • Primary authentication allows you to verify the username and password credentials for a user.
    • Multifactor authentication (MFA) strengthens the security of password-based authentication by requiring additional verification of another Factor. For example, in addition to a password, MFA can require a temporary one-time passcode or an SMS passcode. The Authentication API supports user enrollment with MFA factors enabled by the admin, and MFA challenges based on your global session policy.
    • Recovery allows users to securely reset their password if they've forgotten it, or unlock their account if they're locked out due to excessive failed sign-in attempts. This functionality is subject to the security policy set by the admin.

    Application types

    The behavior of the Okta Authentication API varies depending on the type of your app and your org's security policies. For example, your org's global session policy, the MFA Enrollment Policy, or the Password Policy can affect the behavior of the API.

    Note: Policy evaluation is conditional on the client request context (opens new window) such as IP address.

    Note: In Identity Engine, the Multifactor (MFA) enrollment policy name has changed to authenticator enrollment policy (opens new window).

    Public application

    A public app is an app that anonymously starts an authentication or recovery transaction without an API token, such as the Okta Sign-In Widget. Public apps 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 apps are backend apps that act as an authentication broker or sign-in portal for your Okta org. Trusted apps may start an authentication or recovery transaction with an admin API token. Trusted apps may implement their own recovery flows and primary authentication process and may collect other metadata about the user before primary authentication successfully completes.

    Note: Trusted web apps may need to override the client request context (opens new window) to forward the originating client context for the user.

    Get started with authentication

    Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta Management authentication and OpenID Connect & OAuth 2.0 overview.

    Authentication operations

    Primary authentication

    POST /api/v1/authn

    Every authentication transaction starts with primary authentication that validates a user's primary password credential. Password Policy, MFA Policy, and sign-on policy are evaluated during primary authentication. They're evaluated 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 status, group memberships, and assigned policies.

    Note: In Identity Engine, the MFA Enrollment Policy name is called the authenticator enrollment policy (opens new window).

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

    Note: Enable MFA factors and assign a valid sign-on policy to a user before you enroll and/or verify an 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
    options Opt in features for the authentication transaction Body Options object FALSE
    context Provides more context for the authentication transaction Body Context 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 through the following opt-in features:

    Property Description DataType Nullable Unique Readonly
    multiOptionalFactorEnroll Transitions transaction back to MFA_ENROLL state after successful Factor enrollment when other 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 other context for the authentication or recovery transaction.

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

    Caution: The deviceToken parameter isn't shared between the Authentication API and the Okta Identity Engine-specific APIs. See Upgrade to Okta Identity Engine (opens new window) and Device token behavior changed.

    Note:

    • Overriding context, such as deviceToken, is a highly privileged operation limited to trusted web apps. This requires the app to use a valid admin API token when making authentication or recovery requests. If an API token isn't provided, the deviceToken is ignored.

    • Authentication requests that include a Factor challenge with a per-device or per-session sign-on policy must always include the same deviceToken for the user. If the deviceToken is absent or doesn’t match the previous deviceToken, Okta issues a challenge with every authentication attempt.

    • Authentication requests to Orgs with the New Device Behavior Detection sign-on policy must always include the same deviceToken for a user. 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 (opens new window).

    Device Token best practices

    Use the following recommendations as guidelines for generating and storing a deviceToken for both web and local 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 (opens new window) for more best practices on hardening HTTP cookies.

    Local apps
    Ask the device operating system for a unique device ID. See Apple's information on DeviceCheck (opens new window) for an example.

    Response parameters