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.

Notes:

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": {}
}