Learn how to build your app on Okta, fast. Quick Starts
Edit Page

Sessions API

Okta uses a cookie-based authentication mechanism to maintain a user’s authentication session across web requests. The Okta Sessions API provides operations to create and manage authentication sessions for users in your Okta organization.

Okta utilizes a HTTP session cookie to provide access to your Okta organization and applications across web requests for an interactive user agent such as a web browser. Session cookies have an expiration configurable by an administrator for the organization and are valid until the cookie expires or the user closes the session (logout) or browser application.

Session Token

A session token is a one-time bearer token that provides proof of authentication and may be redeemed for an interactive SSO session in Okta in a user agent. Session tokens can only be used once to establish a session for a user and are revoked when the token expires.

Okta provides a very rich Authentication API to validate a user’s primary credentials and secondary MFA factor. A session token is returned after successful authentication which can be later exchanged for a session cookie using one of the following flows:

Session Tokens are secrets and should be protected at rest as well as during transit. A session token for a user is equivalent to having the user’s actual credentials.

Getting Started

Explore the Sessions API: Run in Postman

Session Operations

Create Session with Session Token

POST /api/v1/sessions

Creates a new session for a user with a valid session token. Use this API if, for example, you want to set the session cookie yourself instead of allowing Okta to set it, or want to hold the session ID in order to delete a session via the API instead of visiting the logout URL.

Don’t use this API unless you need a session id. Instead, use one of the following flows to obtain a SSO session with a sessionToken:

This operation can be performed anonymously without an API Token.

Request Parameters
Parameter Description Param Type DataType Required Default
additionalFields Optional session properties Query String (comma separated values) FALSE  
sessionToken Session token obtained via Authentication API Body String TRUE  
Response Parameters

The response will contain the new Session for the user if the sessionToken was valid.

If an invalid sessionToken is provided, a 401 Unauthorized status code will be returned.

Request Example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
  "sessionToken": "00HiohZYpJgMSHwmL9TQy7RRzuY-q9soKp1SPmYYow"
}' "https://{yourOktaDomain}/api/v1/sessions"
Response Example
{
  "id": "101W_juydrDRByB7fUdRyE2JQ",
  "login": "user@example.com",
  "userId": "00ubgaSARVOQDIOXMORI",
  "expiresAt": "2015-08-30T18:41:35.818Z",
  "status": "ACTIVE",
  "lastPasswordVerification": "2015-08-30T18:41:35.818Z",
  "lastFactorVerification": null,
  "amr": [
    "pwd"
  ],
  "idp": {
    "id": "00oi5cpnylv792IcF0g3",
    "type": "OKTA"
  },
  "mfaActive": false,
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "refresh": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ/lifecycle/refresh",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "user": {
      "name": "Isaac Brock",
      "href": "https://{yourOktaDomain}/api/v1/users/00uit00ZK6ELuzPoD0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Get Session

GET /api/v1/sessions/${sessionId}

Get session information for a given session id.

Note this is an administrator operation and requires an API token.

Request Example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ"
Response Example

If the session is valid, a Session Object is returned.

If the session is invalid, a 404 Not Found response will be returned.

{
  "id": "101W_juydrDRByB7fUdRyE2JQ",
  "login": "user@example.com",
  "userId": "00u0abcdefGHIJKLMNOP",
  "status": "ACTIVE",
  "expiresAt": "2016-01-03T09:13:17.000Z",
  "lastPasswordVerification": "2016-01-03T07:02:00.000Z",
  "lastFactorVerification": null,
  "amr": [
    "pwd"
  ],
  "idp": {
    "id": "01a2bcdef3GHIJKLMNOP",
    "type": "OKTA"
  },
  "mfaActive": true,
  "_links": {
    "refresh": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ/lifecycle/refresh",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ",
      "hints": {
        "allow": [
           "GET",
           "DELETE"
        ]
      }
    },
    "user": {
      "name": "Isaac Brock",
      "href": "https://{yourOktaDomain}/api/v1/users/00uit00ZK6ELuzPoD0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Extend Session

PUT /api/v1/sessions/${sessionId} Deprecated

Extends the lifetime of a user’s session.

This endpoint is deprecated. Use the Refresh Session API instead.

Note this is an administrator operation and requires an API token.

Request Parameters
Parameter Description Param Type DataType Required Default
id id of a valid session URL String TRUE  
Response Parameters

The response will contain the extended Session with an updated expiresAt timestamp for the user if the id was valid.

If the session is invalid, a 404 Not Found response will be returned.

Request Example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ"
Response Example
{
  "id": "101W_juydrDRByB7fUdRyE2JQ",
  "login": "user@example.com",
  "userId": "00ubgaSARVOQDIOXMORI",
  "expiresAt": "2015-08-30T18:41:35.818Z",
  "status": "ACTIVE",
  "lastPasswordVerification": "2015-08-30T18:41:35.818Z",
  "lastFactorVerification": null,
  "amr": [
    "pwd"
  ],
  "idp": {
    "id": "00oi5cpnylv792IcF0g3",
    "type": "OKTA"
  },
  "mfaActive": false,
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "refresh": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ/lifecycle/refresh",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "user": {
      "name": "Isaac Brock",
      "href": "https://{yourOktaDomain}/api/v1/users/00uit00ZK6ELuzPoD0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Refresh Session

Refresh an existing session using the id for that session. (This is equivalent to the deprecated Extend Session operation).

Note this is an administrator operation and requires an API token.

POST /api/v1/sessions/${sessionId}/lifecycle/refresh

Request Parameters
Parameter Description Param Type DataType Required Default
id id of a valid session URL String TRUE  
Response Parameters

The response will contain the refreshed Session with an updated expiresAt timestamp for the user if the id was valid.

If the session is invalid, a 404 Not Found response will be returned.

Request Example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ/lifecycle/refresh"
Response Example
{
  "id": "101W_juydrDRByB7fUdRyE2JQ",
  "login": "user@example.com",
  "userId": "00ubgaSARVOQDIOXMORI",
  "expiresAt": "2015-08-30T18:41:35.818Z",
  "status": "ACTIVE",
  "lastPasswordVerification": "2015-08-30T18:41:35.818Z",
  "lastFactorVerification": null,
  "amr": [
    "pwd"
  ],
  "idp": {
    "id": "00oi5cpnylv792IcF0g3",
    "type": "OKTA"
  },
  "mfaActive": false,
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "refresh": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ/lifecycle/refresh",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "user": {
      "name": "Isaac Brock",
      "href": "https://{yourOktaDomain}/api/v1/users/00uit00ZK6ELuzPoD0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Close Session

DELETE /api/v1/sessions/${sessionId}

Closes a user’s session (logout).

Note this is an administrator operation and requires an API token.

Request Parameters
Parameter Description Param Type DataType Required Default
id id of a valid session URL String TRUE  
Response Parameters

If the session was successfully closed, a 204 No Content response will be returned.

If the session is invalid, a 404 Not Found response will be returned.

Request Example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ"
Response Example
HTTP/1.1 204 No Content

Get Current Session

GET /api/v1/sessions/me CORS

Get session information for the current user. Use this method in a browser based application to determine if the user is logged in.

This operation requires a session cookie for the user. API token is not allowed for this operation.

Request Example
curl -v -X GET \
-H "Accept: application/json" \
-H "Cookie: ${okta_session_cookie}"
"https://{yourOktaDomain}/api/v1/sessions/me"
Response Example

If the session is valid, a Session Object is returned.

If the session is invalid, a 404 Not Found response will be returned.

{
    "id": "101W_juydrDRByB7fUdRyE2JQ",
    "login": "user@example.com",
    "userId": "00u0abcdefGHIJKLMNOP",
    "status": "ACTIVE",
    "createdAt": "2016-01-03T07:02:00.000Z",
    "expiresAt": "2016-01-03T09:13:17.000Z",
    "lastPasswordVerification": "2016-01-03T07:02:00.000Z",
    "lastFactorVerification": null,
    "amr": [
        "pwd"
    ],
    "idp": {
        "id": "01a2bcdef3GHIJKLMNOP",
        "type": "OKTA"
    },
    "mfaActive": true,
    "_links": {
        "refresh": {
            "href": "https://{yourOktaDomain}/api/v1/sessions/me/lifecycle/refresh",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/sessions/me",
            "hints": {
                "allow": [
                    "GET",
                    "DELETE"
                ]
            }
        },
        "user": {
            "name": "Isaac Brock",
            "href": "https://{yourOktaDomain}/api/v1/users/me",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

Refresh Current Session

Refresh the session for the current user.

This operation requires a session cookie for the user. API token is not allowed for this operation.

POST /api/v1/sessions/me/lifecycle/refresh CORS

Request Example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Cookie: ${okta_session_cookie}" \
"https://{yourOktaDomain}/api/v1/sessions/me/lifecycle/refresh"
Response Example

If the session is valid, a Session Object is returned.

If the session is invalid, a 404 Not Found response will be returned.

{
    "id": "101W_juydrDRByB7fUdRyE2JQ",
    "login": "user@example.com",
    "userId": "00u0abcdefGHIJKLMNOP",
    "status": "ACTIVE",
    "createdAt": "2016-01-03T07:02:00.000Z",
    "expiresAt": "2016-01-03T09:13:17.000Z",
    "lastPasswordVerification": "2016-01-03T07:02:00.000Z",
    "lastFactorVerification": null,
    "amr": [
        "pwd"
    ],
    "idp": {
        "id": "01a2bcdef3GHIJKLMNOP",
        "type": "OKTA"
    },
    "mfaActive": true,
    "_links": {
        "refresh": {
            "href": "https://{yourOktaDomain}/api/v1/sessions/me/lifecycle/refresh",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        },
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/sessions/me",
            "hints": {
                "allow": [
                    "GET",
                    "DELETE"
                ]
            }
        },
        "user": {
            "name": "Isaac Brock",
            "href": "https://{yourOktaDomain}/api/v1/users/me",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        }
    }
}

Option: Use the HTTP Header Prefer

Okta now supports the HTTP Header Prefer in the Sessions API for refreshing sessions. You can extend the session lifetime, but skip any processing work related to building the response body.

Request Example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Prefer: return=minimal" \
-H "Authorization: SSWS ${api_token}" \
"https://{yourOktaDomain}/api/v1/sessions/me/refresh"

Note: me can also be an ID.

Response Example
HTTP/1.1 204 No Content
Preference-Applied: return=minimal

Close Current Session

Close the session for the currently logged in user. Use this method in a browser-based application to log a user out.

This operation requires a session cookie for the user. API token is not allowed for this operation.

DELETE /api/v1/sessions/me CORS

Request Example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Cookie: ${okta_session_cookie}" \
"https://{yourOktaDomain}/api/v1/sessions/me"
Response Example

If the session was successfully closed, a 204 No Content response will be returned.

If the session is invalid, a 404 Not Found response will be returned.

HTTP/1.1 204 No Content

Session Model

Example

{
  "id": "101W_juydrDRByB7fUdRyE2JQ",
  "login": "user@example.com",
  "userId": "00ubgaSARVOQDIOXMORI",
  "expiresAt": "2015-08-30T18:41:35.818Z",
  "status": "ACTIVE",
  "lastPasswordVerification": "2015-08-30T18:41:35.818Z",
  "lastFactorVerification": "2015-08-30T18:41:35.818Z",
  "amr": [
    "pwd",
    "otp",
    "mfa"
  ],
  "idp": {
    "id": "00oi5cpnylv792IcF0g3",
    "type": "OKTA"
  },
  "mfaActive": true,
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "refresh": {
      "href": "https://{yourOktaDomain}/api/v1/sessions/101W_juydrDRByB7fUdRyE2JQ/lifecycle/refresh",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "user": {
      "name": "Isaac Brock",
      "href": "https://{yourOktaDomain}/api/v1/users/00uit00ZK6ELuzPoD0g3",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Session Properties

Sessions have the following properties:

Property Description DataType Nullable Unique Readonly
id unique key for the session String FALSE TRUE TRUE
login unique identifier for the user (username) String FALSE TRUE TRUE
userId unique key for the user String FALSE TRUE TRUE
expiresAt timestamp when session expires Date FALSE TRUE TRUE
status current status of the session ACTIVE, MFA_REQUIRED, or MFA_ENROLL FALSE TRUE TRUE
lastPasswordVerification timestamp when user last performed primary or step-up authentication with password Date TRUE TRUE TRUE
lastFactorVerification timestamp when user last performed multi-factor authentication Date TRUE TRUE TRUE
amr authentication method reference AMR Object FALSE FALSE TRUE
idp identity provider used to authenticate the user IDP Object FALSE FALSE TRUE
mfaActive indicates whether the user has enrolled an MFA factor Boolean FALSE FALSE TRUE

The mfaActive parameter is a Deprecated feature. Use the lastFactorVerification attribute in conjunction with amr to understand if the user has performed MFA for the current session. Use the Factors API to query the factor enrollment status for a given user.

Optional Session Properties

The Create Session operation can optionally return the following properties when requested.

Property Description
cookieToken Another one-time token which can be used to obtain a session cookie by visiting either an application’s embed link or a session redirect URL.
cookieTokenUrl URL for a a transparent 1x1 pixel image which contains a one-time session token which when visited sets the session cookie in your browser for your organization.

The cookieToken is a Deprecated property. Instead, use the Authentication API, which supports the full user authentication pipeline and produces a sessionToken which can be used in this API.

The cookieTokenUrl is a Deprecated property, because modern browsers block cookies set via embedding images from another origin (cross-domain).

Session Status

The following values are defined for the status of a session:

  • ACTIVE: the session is established and fully validated
  • MFA_REQUIRED: the session is established but requires second factor verification
  • MFA_ENROLL: the session is established but the user needs to enroll in a second factor

AMR Object

The authentication methods reference (“AMR”) specifies which authentication methods were used to establish the session. The value is a JSON array with one or more of the following values:

Value Description Example
pwd Password authentication Standard password-based login
swk Proof-of-possession (PoP) of a software key Okta Verify with Push
hwk Proof-of-possession (PoP) of a hardware key Yubikey factor
otp One-time password Okta Verify, Google Authenticator
sms SMS text message to the user at a registered number SMS factor
tel Telephone call to the user at a registered number Phone call factor
geo Use of geo-location information IP Trust and Network Zone policy conditions
fpt Fingerprint biometric authentication Okta Verify with Touch ID
kba Knowledge-based authentication Security Question factor
mfa Multiple-factor authentication This value is present whenever any MFA factor verification is performed.
mca Multiple-channel authentication Authentication requires communication over more than one channel, such as Internet and mobile network.

IDP Object

Specifies the identity provider used to authentication the user.

Property DataType Nullable Unique Readonly MinLength MaxLength Validation
id String FALSE FALSE TRUE      
type OKTA, ACTIVE_DIRECTORY, LDAP, FEDERATION, or SOCIAL FALSE FALSE TRUE      

The id will be the org id if the type is OKTA; otherwise it will be the IDP instance id.

{
  "idp": {
    "id": "0oabhnUQFYHMBNVSVXMV",
    "type": "ACTIVE_DIRECTORY"
  }
}