On this 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.
Note: Some browsers block third-party cookies by default, which disrupts Okta functionality in certain flows. See FAQ: How Blocked Third Party Cookies Can Potentially Impact Your Okta Environment (opens new window).
Note: The Sessions API doesn't support direct authentication. Direct authentication is supported through the Authentication API or through OIDC using the Resource Owner Password flow.
Session cookie
Okta uses an 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. A session cookie has an expiration configurable by an administrator for the organization and is 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 that uses one of the following flows:
- Retrieve a session cookie by visiting the OpenID Connect Authorization Endpoint
- Retrieve a session cookie by visiting a session redirect link
- Retrieve a session cookie by visiting an application embed link
Note: Session tokens are secrets and should be protected at rest and during transit. A session token for a user is equivalent to having the user's actual credentials.
Get started
Explore the Sessions API: (opens new window)
Session operations
Create Session with a 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 you want to hold the Session ID to delete a Session through 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
:
- Retrieving a session cookie by visiting the OpenID Connect Authorization Endpoint
- Retrieving a session cookie by visiting a session redirect link
- Retrieving a session cookie by visiting an application embed link
Note: 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 | The session token obtained through the Authentication API | Body | String | TRUE |
Response parameters
The response contains the new Session for the user if the sessionToken
is valid.
If an invalid sessionToken
is provided, a 401 Unauthorized
status code is returned.
Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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}
Gets 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 "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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 is 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}
DeprecatedExtends the lifetime of a user's Session
Note: 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 contains the extended Session with an updated expiresAt
timestamp for the user if the id
is valid.
If the Session is invalid, a 404 Not Found
response is returned.
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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
Refreshes 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 contains the refreshed Session with an updated expiresAt
timestamp for the user if the id
is valid.
If the Session is invalid, a 404 Not Found
response is returned.
Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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 is successfully closed, a 204 No Content
response is returned.
If the Session is invalid, a 404 Not Found
response is returned.
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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
CORSGets Session information for the current user. Use this method in a browser-based application to determine if the user is signed in.
Note: This operation requires a session cookie for the user. An API token isn't allowed for this operation.
Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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 is 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
Refreshes the Session for the current user
Note: This operation requires a session cookie for the user. An API token isn't allowed for this operation.
POST /api/v1/sessions/me/lifecycle/refresh
CORSRequest example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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 is 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
(opens new window) in the Sessions API for refreshing Sessions. You can extend the Session lifetime, but skip any processing work that is related to building the response body.
Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-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
Closes the Session for the user who is currently signed in. Use this method in a browser-based application to sign out a user.
Note: This operation requires a session cookie for the user. An API token isn't allowed for this operation.
DELETE /api/v1/sessions/me
CORSRequest example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Cookie: ${okta_session_cookie}" \
"https://${yourOktaDomain}/api/v1/sessions/me"
Response example
If the Session is successfully closed, a 204 No Content
response is returned.
If the Session is invalid, a 404 Not Found
response is returned.
HTTP/1.1 204 No Content
Session object
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 | A unique key for the Session | String | FALSE | TRUE | TRUE |
login | A unique identifier for the user (username) | String | FALSE | TRUE | TRUE |
userId | A unique key for the user | String | FALSE | TRUE | TRUE |
expiresAt | A timestamp when the Session expires | Date | FALSE | TRUE | TRUE |
status | Current status of the Session | ACTIVE , MFA_REQUIRED , or MFA_ENROLL | FALSE | TRUE | TRUE |
lastPasswordVerification | A timestamp when the user last performs the primary or step-up authentication with a password | Date | TRUE | TRUE | TRUE |
lastFactorVerification | A timestamp when user last performs multifactor authentication | Date | TRUE | TRUE | TRUE |
amr | Authentication method reference | AMR object | FALSE | FALSE | TRUE |
idp | The Identity Provider that is used to authenticate the user | IDP object | FALSE | FALSE | TRUE |
mfaActive | Indicates whether the user has enrolled an MFA factor | Boolean | FALSE | FALSE | TRUE |
Note: The
mfaActive
parameter is a Deprecated feature. Use thelastFactorVerification
attribute in conjunction withamr
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 that is used to obtain a session cookie by visiting either an application's embed link or a Session redirect URL. |
cookieTokenUrl | The URL for a transparent 1x1 pixel image that contains a one-time session token that, when visited, sets the session cookie in your browser for your organization. |
Note: The
cookieToken
is a Deprecated property. Instead, use the Authentication API that supports the full user authentication pipeline and produces asessionToken
that you can use in this API.
Note: The
cookieTokenUrl
is a Deprecated property, because modern browsers block cookies that are set through 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 (opens new window) ("AMR") specifies which authentication methods are used to establish the Session. The value is a JSON array with one or more of the following values:
Note: For inline hook requests, use the inline hook value for the
amr
object.
Value | Inline hook value | Description | Example |
---|---|---|---|
pwd | PASSWORD | Password authentication | Standard password-based login |
swk | POP_SOFTWARE_KEY | Proof-of-possession (PoP) of a software key | Okta Verify with Push |
hwk | POP_HARDWARE_KEY | Proof-of-possession (PoP) of a hardware key | Yubikey factor |
otp | ONE_TIME_PASSWORD | One-time password | Okta Verify, Google Authenticator |
sms | SMS_MESSAGE | SMS text message to the user at a registered number | SMS factor |
tel | TELEPHONE_CALL | Telephone call to the user at a registered number | Phone call factor |
geo | GEOLOCATION | Use of geo-location information | IP Trust and Network Zone policy conditions |
fpt | BIO_FINGERPRINT | Fingerprint biometric authentication | Okta Verify with Touch ID |
kba | KNOWLEDGE_BASED_AUTHENTICATION | Knowledge-based authentication | Security Question factor |
mfa | MULTIFACTOR_AUTHENTICATION | Multiple-factor authentication | This value is present whenever any MFA factor verification is performed. |
mca | MULTIPLE_CHANNEL_AUTHENTICATION | Multiple-channel authentication | Authentication requires communication over more than one channel, such as Internet and mobile network. |
sc | SMART_CARD | Smart card authentication | User authenticated using a smart card, such as a Personal Identity Verification (PIV) card or Common Access Card (CAC) |
IDP object
Specifies the Identity Provider that is used to authenticate 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 |
Note: The
id
is the org ID if the type isOKTA
. Otherwise, it is the IDP instance ID.
{
"idp": {
"id": "0oabhnUQFYHMBNVSVXMV",
"type": "ACTIVE_DIRECTORY"
}
}