Reference overview

This topic contains information and details related to the design principles of the Okta API.

Note: For Classic Engine only APIs, see Classic Engine APIs.

URL namespace

All URLs listed in the documentation should be preceded with your org'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 app 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.

https://{yourOktaDomain}/api/v1/users

Note: Identity Governance Access Requests for resource catalogs APIs use version v2.

Authentication

You can access Okta APIs with either an OAuth 2.0 access token or an API token. Okta recommends using scoped OAuth 2.0 access tokens. See Authentication.

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

Note: 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.

All Date objects are returned in ISO 8601 format:

YYYY-MM-DDTHH:mm:ss.SSSZ

Character sets

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%3A00%3A00.000Z%22

Notes:

• 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) and https:// 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.
• If you use the special character " within a quoted string, you must also escape it (\) and encode it. For example, search=profile.lastName eq "bob"smith" is encoded as search=profile.lastName%20eq%20%22bob%5C%22smith%22.

HTTP verbs

Where possible, the Okta API strives to use appropriate HTTP verbs for each action.

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

Note: If your app 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

Use a template to format the string

User-Agent: Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>

Pass a hint about the browser

Pass operating system information

• iOS: Include the words apple or ios 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

Note: The public IP address of your trusted web app 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

Device Fingerprint

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 type
• errorLink: Currently returns the same value as the errorCode
• errorSummary: A natural language explanation of the error
• errorId: 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 the errorCode property is supported for runtime error flow control. The errorSummary property is only intended for troubleshooting and may change over time.

Conditional Requests and Entity Tags

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "W/\"1234567890abcdef\""

{
    "id": "00ub0oNGTSWTBKOLGLNR",
    "profile": {
        "firstName": "Isaac",
        "lastName": "Brock",
        "email": "isaac.brock@example.com"
    }
}

POST /api/v1/users/00ub0oNGTSWTBKOLGLNR HTTP/1.1
Host: example.okta.com
Authorization: <YOUR_API_KEY_HERE>
Content-Type: application/json
If-Match: "W/\"1234567890abcdef\""

{
    "profile": {
        "email": "isaac@example.com"
    }
}

Note: This feature is currently only supported when creating and updating user profiles. See Users API.

Pagination

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"

Filter

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"

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

The following operators from the SCIM Protocol Specification are supported:

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 using lt ... 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 format YYYY-MM-DDTHH:mm:ss.SSSZ.
• The System Log supports the contains (co) and ends with (ew) operators.

Contains operator

• Users API
• Groups API
• Devices API
• Realms API

Other APIs do not support this operator.

Attribute operators

Logical operators

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 app. 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 type application/hal+json isn't currently supported as a formal media type for content negotiation. Use the standard application/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 a 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.

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:

HTTP/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 app that needs CORS, check that the specific operation supports CORS for your use case. APIs that support CORS are marked with the CORS icon.