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.

Retrieve a session
OAuth 2.0 scopes:
  • 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 scopes:
  • 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 scopes:
  • 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": {}
}