Reference overview
This topic contains information and details related to the design principles of the Okta API.
URL namespace
All URLs listed in the documentation should be preceded with your organization's subdomain (tenant) or configured custom domain.
Note: All API requests must use the HTTPS scheme.
API Versions
The Okta API is a versioned API. Okta reserves the right to add new parameters, properties, or objects to the API without advance notice. These updates are considered non-breaking and the compatibility rules outlined in this topic should be followed to ensure your application remains operational. Breaking changes, such as removing or renaming a property, are released as a new version of the API. Okta will provide a migration path for new versions of APIs and will communicate timelines for end-of-life when deprecating APIs.
The API version is included in the path. For example, the Users API currently uses versionv1
:https://{yourOktaDomain}/api/v1/users
Note
Don't consume any Okta API not documented by this reference portal. All undocumented endpoints are considered private, subject to change without notice, and not covered by any agreements.
Compatibility rules
Input parameters
- Requests are compatible irrespective of the order in which the query parameters appear.
- Requests are compatible irrespective of the order in which the properties of the JSON parameters appear.
- New query parameters may be added to future versions of requests.
- Existing query parameters can’t be removed from future versions of requests.
- Existing properties can’t be removed from the JSON parameters in future versions of requests.
JSON responses
- Responses are compatible irrespective of the order in which the properties appear.
- New properties may be added to future versions of the response.
- Existing properties can’t be removed from future versions of the response.
- Properties with null values may be omitted by responses.
Media types
The API currently supports only JSON as an exchange format. Be sure to set both theNote: JSON responses, including errors, may contain user input. To help prevent potential cross-site scripting attacks, make sure to properly escape all values before use in a browser or any HTML context.
Content-Type
and Accept
headers for every request as application/json
.All Date objects are returned in ISO 8601 format:
YYYY-MM-DDTHH:mm:ss.SSSZ
Character sets
Okta supports a subset of theUTF-8
specification. Specifically, this includes any character that can be encoded in three bytes or less. BMP characters and supplementary characters that must be encoded using four bytes aren't currently supported.Special characters
Certain query parameters, such as when filtering, require percent encoding to ensure correct interpretation of special characters. See Percent Encoding.
Consider the following example:
filter=lastUpdated gt "2013-06-01T00:00:00.000Z"
This is encoded to the following:
filter=lastUpdated%20gt%20%222013-06-01T00:00:00.000Z%22
Note: Don't encode delimiters, which are essential parts of the request structure. Common examples of this include the question mark before the query (like?name
) andhttps://
at the start of a URL. Incorrectly encoding delimiters can result in an error. See Encode Query and Special characters and delimiters in the help documentation.
HTTP verbs
Where possible, the Okta API strives to use appropriate HTTP verbs for each action.
Verb | Description |
---|---|
GET | Used to retrieve objects |
PATCH | Used to partially update objects. Where supported, Okta implements one or both of JSON Patch and JSON Merge Patch. Note: Not all APIs implement PATCH for updates. |
POST | Used to create objects or perform custom actions (such as user lifecycle operations). For POST requests without a body param, you must include a Content-Length: 0 header. |
PUT | Used to replace objects or collections. For PUT requests without a body param, you must include a Content-Length: 0 header. |
DELETE | Used to delete objects |
Note: Okta API services may respond to PUT or POST requests with an HTTP 400 or 411 status code in a few situations:
- The request doesn't contain an entity body and there's no valid Content-Length header included
- The request includes the entity body, but doesn't use chunked transfer encoding, and doesn't include a valid Content-Length header
Client request context
Okta derives the client request context directly from the HTTP request headers and the client TCP socket. The request context is used to evaluate policies such as Global Session Policy and provide client information for troubleshooting and auditing purposes.
User Agent
Okta supports the standardUser-Agent
HTTP header to identify the user's browser or application. Always send a User-Agent
string to uniquely identify your client application and version, for example: Oktaprise/1.1
.Note: If your application is acting as a gateway or proxy, you should forward the User-Agent
of the originating client with your API requests.
Format a User-Agent string
Ensure that theUser-Agent
string that your app constructs is in the correct format so that Okta can parse the OS
and Browser
fields. Okta can correctly parse User-Agent
strings that contain browser and system information, platform details, and any extensions.Use a template to format the string
Okta recommends that you use a template like the following to format theUser-Agent
string:User-Agent: Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>
OS
and Browser
fields from the User-Agent
header passed from your application.If the OS
and/or Browser
fields come back as Unknown
in the System Log, ensure that certain string values are present in the User-Agent
string so that the OS and browser are detected.Pass a hint about the browser
Add browser information such aschrome
or safari
to the User-Agent
string.Pass operating system information
- iOS: Include the words
apple
orios
and at least one of these values:iphone
,ipad
,ipod
,ipad
. - Android: Include the word
android
, which infers that Android is the operating system.
IP address
The public IP address of your application is automatically used as the client IP address for your request. Okta supports the standardX-Forwarded-For
HTTP header to forward the originating client's IP address if your application is behind a proxy server or acting as a sign-in portal or gateway.Note: The public IP address of your trusted web application must be a part of the allowlist in your org's network security settings as a trusted proxy to forward the user agent's original IP address with the X-Forwarded-For
HTTP header.
Accept Language
TheAccept-Language
HTTP header advertises which languages the client is able to understand, for example Accept-Language: en-US
. Include the header if it's available.Device Fingerprint
TheX-Device-Fingerprint
HTTP header supplies the device fingerprint used in an authentication request.Errors
Note: JSON responses, including errors, may contain user input. To help prevent potential cross-site scripting attacks, ensure to properly escape all values before use in a browser or any HTML context.
All successful requests return a 200 status if there’s content to return or a 204 status if there’s no content to return.
All requests that result in an error return the appropriate 4xx or 5xx error code with a custom JSON error object:
errorCode
: A code that is associated with this error typeerrorLink
: Currently returns the same value as theerrorCode
errorSummary
: A natural language explanation of the errorerrorId
: An ID that identifies this request. These IDs are mapped to the internal error on the server side to assist in troubleshooting.
{
"errorCode": "E0000001",
"errorSummary": "Api validation failed",
"errorLink": "E0000001",
"errorId": "oaeHfmOAx1iRLa0H10DeMz5fQ",
"errorCauses": [
{
"errorSummary": "login: An object with this field already exists in the current organization"
}
]
}
See Error Codes for a list of API error codes.
Note: Only theerrorCode
property is supported for runtime error flow control. TheerrorSummary
property is only intended for troubleshooting and may change over time.
Pagination
Requests that return a list of objects may support pagination. Pagination is based on a cursor and not on page number. The cursor is opaque to the client and specified in either thebefore
or after
query parameter. For some objects, you can also set a custom page size with the limit
parameter.Param | Description |
---|---|
before | The cursor that points to the start of the page of data that has been returned. |
after | The cursor that points to the end of the page of data that has been returned. |
limit | The number of individual objects that are returned in each page. |
Link header
Pagination links are included in the Link header of responses. It's important to follow these Link header values instead of constructing your own URLs as query parameters or cursor formats may change without notice.
HTTP/1.1 200 OK
link: <https://{yourOktaDomain}/api/v1/logs?limit=20>; rel="self"
link: <https://{yourOktaDomain}/api/v1/logs?limit=20&after=1627500044869_1>; rel="next"
rel
values are:Link relation type | Description |
---|---|
self | Specifies the URL of the current page of results |
next | Specifies the URL of the immediate next page of results |
next
link value with the response. This holds true for all cases, except for the System Log API where the next
link always exists in System Log polling queries. A polling query is defined as an ASCENDING
query with an empty or absent until
parameter, providing a stream of data.Filter
Filtering allows a requestor to specify a subset of objects to return and is often needed for large collection objects such asUsers
. While filtering semantics are standardized in the Okta API, not all objects in the Okta API support filtering. When filtering is supported for an object, the filter
URL query parameter contains a filter expression.The Expression Language that is used in the filter and search parameters supports references to JSON attributes and literals. The literal values can be strings enclosed in double quotes, numbers, date times enclosed in double quotes, and boolean values (for example, true or false). String literals must be valid JSON strings.
The attribute names are case-sensitive while attribute operators are case-insensitive. For example, the following two expressions evaluate to the same logical value:
filter=profile.firstName Eq "john"
filter=profile.firstName eq "john"
()
. If your expression contains special characters, make sure you encode the parameter.Note: Each object in the Okta API defines what attributes and operators are supported for the expression. See object-specific documentation for more information.
Operators
Most of the operators listed in the SCIM Protocol Specification are supported:
Operator | Description | Behavior |
---|---|---|
eq | equal | Matches if the attribute and operand values are identical |
ge | greater than or equal | Matches if the attribute value is greater than or equal to the operand value. The actual comparison depends on the attribute type. String attribute types are a lexicographical comparison and Date types are a chronological comparison. |
gt | greater than | Matches if the attribute value is greater than the operand value. The actual comparison depends on the attribute type. String attribute types are a lexicographical comparison and Date types are a chronological comparison. |
le | less than or equal | Matches if the attribute value is less than or equal to the operand value. The actual comparison depends on the attribute type. String attribute types are a lexicographical comparison and Date types are a chronological comparison. |
lt | less than | Matches if the attribute value is less than the operand value. The actual comparison depends on the attribute type. String attribute types are a lexicographical comparison and Date types are a chronological comparison. |
ne | not equal | Matches if the attribute value doesn't match the operand value |
pr | present (has value) | Matches if the attribute has a non-empty value or if it contains a non-empty node for complex attributes |
sw | starts with | The entire operand value must be a substring of the attribute value that starts at the beginning of the attribute value. This criterion is satisfied if the two strings are identical. |
ew | ends with | The entire operand value must be a substring of the attribute value that starts at the end of the attribute value. This criterion is satisfied if the two strings are identical. This operator is only usable with the System Log API. |
Notes:
- Some objects don't support all the listed operators.
- The
ne
(not equal) operator isn't supported for some objects, but you can obtain the same result by usinglt ... or ... gt
. For example, to see all user agents except for "iOS", use(client.userAgent.os lt "iOS" or client.userAgent.os gt "iOS")
.- All
Date
values use the ISO 8601 formatYYYY-MM-DDTHH:mm:ss.SSSZ
.- The System Log API supports the contains (
co
) and ends with (ew
) operators.
Attribute operators
Operator | Description | Behavior |
---|---|---|
and | Logical AND | The filter is only a match if both expressions evaluate to true. |
not | Logical NOT | The filter is a match if the expression evaluates to false. |
or | Logical OR | The filter is a match if either expression evaluates to true. |
Logical operators
Operator | Description | Behavior |
---|---|---|
() | Precedence grouping | Boolean expressions may be grouped by using parentheses to change the standard order of operations, for example, evaluate OR logical operators before logical AND operators. |
AND
operator, followed by the logical OR
operator.Hypermedia
Objects in the Okta API use hypermedia for discoverability. Hypermedia enables API clients to navigate objects by following links like a web browser instead of hard-coding URLs in your application. Links are identified by link relations that are named keys. Link relations describe what objects are available and how API clients can interact with them. Each object may publish a set of link relationships based on the state of the object. For example, the status of a user in the User API governs which lifecycle operations are permitted. Only the permitted operations are published as lifecycle operations.
The Okta API incorporates the JSON Hypertext Application Language or HAL formatting as the foundation for hypermedia discoverability. HAL provides a set of conventions for expressing hyperlinks in JSON responses that represent two simple concepts: Resources and Links.
Note: The HAL-specific media typeapplication/hal+json
isn't currently supported as a formal media type for content negotiation. Use the standardapplication/json
media type instead.
Links
Objects with property names that are link relation types (as defined by RFC8288) have values that are either a Link object or an array of Link objects. Link objects contain the following:
- A target URI
- The name of the link relation (
rel
) - Other optional properties to help with deprecation, object state or lifecycle management, content negotiation, and so on.
- Links are implicitly of media type
application/json
. Other media types are only returned in cases where the link isn't an API endpoint.
Note: An object may have multiple links that share link relations. The following example shows this with shared "logo"
link:
{
"_links": {
"logo": [
{
"name": "medium",
"href": "https://{yourOktaDomain}/assets/img/logos/groups/active_directory-medium.b3959116154f9d44bd4d0f6b2ae31ea6.png",
"type": "image/png"
},
{
"name": "large",
"href": "https://{yourOktaDomain}/assets/img/logos/groups/active_directory-large.0e7a58559ac90c4bbc7b33fa14018c50.png",
"type": "image/png"
}
],
"self": { "href": "/example_resource" },
"next": { "href": "/page=2" }
}
}
Links in collections
HAL links that are returned in a collection of resources may not reflect the total set of operations that are possible on that resource. For example, in a user collection, links to indicate that a given user can be unlocked may not be returned and, if returned, may not reflect the correct user state.
Search and list operations are intended to find matching resources and their identifiers. If you intend to search for a resource and then modify its state or make a lifecycle change, the correct pattern is to first retrieve the resource byid
using the self
link provided for that resource in the collection. This provides the full set of lifecycle links for that resource based on its most up-to-date state.Request debugging
The request ID is always present in every API response and can be used for debugging. You can use this value to correlate events from the System Log events.
The following header is set in each response:
X-Okta-Request-Id
- The unique identifier for the API requestHTTP/1.1 200 OK
X-Okta-Request-Id: reqVy8wsvmBQN27h4soUE3ZEnA
Cross-Origin Resource Sharing (CORS)
Cross-Origin Resource Sharing (CORS) is a mechanism that allows a web page to make an AJAX call by using XMLHttpRequest (XHR) to a domain that is different from the one where the script was loaded. Such cross-domain requests would otherwise be forbidden by web browsers, in accordance with the same origin security policy. CORS defines a standardized way in which the browser and the server can interact to determine whether to allow the cross-origin request.
In Okta, CORS allows JavaScript, which is hosted on your websites, to make an XHR to the Okta API with a token. See OpenID Connect & OAuth 2.0.
Every website origin must be explicitly permitted through the Admin Console for CORS. See Enabling CORS for more information on how to allow your website to make cross-origin requests.
Caution: Only grant access to specific origins (websites) that you control and trust to access the Okta API.
CORS support
The Okta API supports CORS on an API by API basis. If you're building an application that needs CORS, check that the specific operation supports CORS for your use case. APIs that support CORS are marked with the CORS icon.