Sessions

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.

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.

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:

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.

Create a Session with session token

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 to delete a session through the API instead of visiting the logout URL.

Request
Request Body schema: application/json
required
sessionToken
string

The session token obtained during authentication

Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/sessions
Request samples
application/json
{
  • "sessionToken": "00HiohZYpJgMSHwmL9TQy7RRzuY-q9soKp1SPmYYow"
}
Response samples
application/json
{
  • "amr": [
    • "pwd"
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "id": "l7FbDVqS8zHSy65uJD85",
  • "idp": {
    • "id": "01a2bcdef3GHIJKLMNOP",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "lastFactorVerification": "2019-08-24T14:15:22Z",
  • "lastPasswordVerification": "2019-08-24T14:15:22Z",
  • "login": "user@example.com",
  • "status": "ACTIVE",
  • "userId": "00u0abcdefGHIJKLMNOP",
  • "_links": {}
}

Retrieve the current Session
CORS

Retrieves 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
header Parameters
Cookie
string

Session ID (sid) or Identity Engine (idx) cookie

Example: sid=abcde-123 or idx=abcde-123
Responses
200

Success

404

Not Found

get/api/v1/sessions/me
Request samples
Response samples
application/json
{}

Close the current Session
CORS

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.

Request
header Parameters
Cookie
string

Session ID (sid) or Identity Engine (idx) cookie

Example: sid=abcde-123 or idx=abcde-123
Responses
204

No Content

404

Not Found

delete/api/v1/sessions/me
Request samples
Response samples
application/json
{
  • "errorCode": "E0000007",
  • "errorSummary": "Not found: {0}",
  • "errorLink": "E0000007",
  • "errorId": "sampleMlLvGUj_YD5v16vkYWY",
  • "errorCauses": [ ]
}

Refresh the current Session
CORS

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.

Request
header Parameters
Cookie
string

Session ID (sid) or Identity Engine (idx) cookie

Example: sid=abcde-123 or idx=abcde-123
Responses
200

Success

404

Not Found

post/api/v1/sessions/me/lifecycle/refresh
Request samples
Response samples
application/json
{}

Retrieve a Session
OAuth 2.0: okta.sessions.read

Retrieves information about the Session specified by the given session ID

Request
path Parameters
sessionId
required
string

id of the Session

Example: l7FbDVqS8zHSy65uJD85
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/sessions/{sessionId}
Request samples
Response samples
application/json
{
  • "amr": [
    • "pwd"
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "id": "l7FbDVqS8zHSy65uJD85",
  • "idp": {
    • "id": "01a2bcdef3GHIJKLMNOP",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "lastFactorVerification": "2019-08-24T14:15:22Z",
  • "lastPasswordVerification": "2019-08-24T14:15:22Z",
  • "login": "user@example.com",
  • "status": "ACTIVE",
  • "userId": "00u0abcdefGHIJKLMNOP",
  • "_links": {}
}

Revoke a Session
OAuth 2.0: okta.sessions.manage

Revokes the specified Session

Request
path Parameters
sessionId
required
string

id of the Session

Example: l7FbDVqS8zHSy65uJD85
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

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

Refresh a Session
OAuth 2.0: okta.sessions.manage

Refreshes an existing Session using the id for that Session. A successful response contains the refreshed Session with an updated expiresAt timestamp.

Request
path Parameters
sessionId
required
string

id of the Session

Example: l7FbDVqS8zHSy65uJD85
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/sessions/{sessionId}/lifecycle/refresh
Request samples
Response samples
application/json
{
  • "amr": [
    • "pwd"
    ],
  • "createdAt": "2019-08-25T14:17:22Z",
  • "expiresAt": "2019-08-25T14:17:22Z",
  • "id": "l7FbDVqS8zHSy65uJD85",
  • "idp": {
    • "id": "01a2bcdef3GHIJKLMNOP",
    • "type": "ACTIVE_DIRECTORY"
    },
  • "lastFactorVerification": "2019-08-24T14:15:22Z",
  • "lastPasswordVerification": "2019-08-24T14:15:22Z",
  • "login": "user@example.com",
  • "status": "ACTIVE",
  • "userId": "00u0abcdefGHIJKLMNOP",
  • "_links": {}
}