Okta Privileged Access is a Privileged Access Management (PAM) solution designed to help customers mitigate the risk of unauthorized access to resources, a critical area of security and risk management in any organization. Okta Privileged Access (OPA) builds on the current server access control capabilities provided by Okta Advanced Server Access and delivers a unified approach to managing access to all your privileged accounts. OPA securely connects people, machines, and applications to privileged resources such as servers, containers, and enterprise apps.

This site documents API operations for Okta Privileged Access. For more documentation, see Okta Privileged Access.


Most operations require an HTTP Authorization header with a value of Bearer AUTH_TOKEN.

To retrieve an auth token, you must first use the Create a Service User endpoint to create a service account and generate an API key. The service account can then pass the API key information to the Issue a Service User token endpoint.

Auth tokens may expire at any time, so prepare any integrations with your systems to handle a 401 Unauthorized response code by creating a new auth token.


Generally, Group memberships define which permissions are available to a User. Each Group assigned to a User grants specific permissions to roles or Projects. For example, you might create a Security Group that grants the resource_admin role to members of the group.

User permissions are equivalent to the most permissive role that they’re granted.

Available roles

Role Description
pam_admin This role allows a user to assign other administrative roles to OPA Groups and Users
resource_admin This role allows a user to administer Project resources. They can create, update, or delete Resource Groups. This role can also assign Delegated Resource Administrators to one or more specific Resource Groups.
delegated_resource_admin This role allows a user to manage all Projects within their assigned Resource Groups
security_admin This role allows a user to create Security Policies that control access to resources. A Security Policy defines which resources are available for access, who can access them, and the available methods to access them.
end_user This role allows a user to view and access resources granted by security policies. This role is automatically assigned to every human user on your OPA Team.


Requests that return lists of objects may support pagination. By default, pagination limits the number of returned objects in a given response to 100.

OPA provides information about pagination in Link headers:

  • A Link header that contains rel="next" indicates that a subsequent page is available and contains the URL used to fetch it.
  • A Link header that contains rel="prev" indicates that a previous page is available and contains the URL used to fetch it.

To fetch a full list of resources, Clients should use the following approach when retrieving lists:

  1. Perform the desired list call without providing any pagination-related parameters.
  2. Process the response body by referencing objects in the body field called list .
  3. Check for a Link header value with rel="next" . If such a value exists, fetch it and repeat steps two and three.

An example of a paginated request that contains the URL from the rel="next" Link header:

curl -v -X GET \
-H "Authorization: Bearer {jwt}" \

Clients that want to fetch pages of fewer than 100 items (for testing pagination, for example) may pass a count parameter to the initial list call. This parameter is automatically propagated to each of the pagination Link URLs that are contained in the response; you only need to provide this parameter with the initial call.

List responses that don't currently implement pagination limits may begin to do so without warning in the future. As a result, Okta recommends you implement pagination when calling any list method. This ensures that the method continues to work if pagination is later implemented.

An example of a paginated response body that contains a list field:

  "list": [
      "id": "5dfc51da-3991-4330-88bf-ef710a7d53e5",
      "name": "everyone",
      "roles": [
      "deleted_at": null
      "id": "ad2ff761-83da-4769-b86c-85042eefc1d7",
      "name": "owners",
      "roles": [
      "deleted_at": null

Rate limits

Rate limits control access to OPA APIs by measuring the rate at which users send requests during a rate limit period. After exceeding this limit, users must wait for requests to replenish before submitting again. Every API response includes headers related to rate limiting:

Header Description
X-RateLimit-Limit A value that indicates the total number of operations permitted per rate limit period
X-RateLimit-Remaining A value that indicates the total number of remaining operations permitted during the current rate limit period
X-RateLimit-Reset A unix timestamp that indicates when the number of rate limit requests fully replenishes
X-RateLimit-Retry-At A unix timestamp that indicates when the number of rate limit requests partially replenishes. If multiple requests share a timestamp, sending them at the same time may cause additional rate limiting

Requests that exceed a rate limit receive an HTTP 429 - Too Many Requests error response. To request a rate limit increase, contact support.


Okta Privileged Access returns the following HTTP errors:

Error Code Description
invalid_request 400 This error is returned on an improper or invalid request body. The request should be modified before being reattempted.
authentication_error 401 A correct API token wasn't provided. A new token should be retrieved before reattempting.
authorization_error 401 The current User doesn't have permission to access the resource requested. Occasionally, this is the result of expired permissions and requires reauthentication.
server_authorization_revoked 401 A previously deleted Server attempted to reconnect with its old token. Re-enroll the Server to remedy this error.
forbidden_error 403 A User requests a resource that they don't have access to.
quota_exceeded 403 A Team exceeded the allotted resource type. Contact support to increase your quota.
disabled_team 403 The OPA Team that is being accessed is disabled. Contact support to resolve this issue.
resource_does_not_exist 404 A resource doesn't exist. Most likely the path parameters of the URL are incorrectly spelled or the specific resource was deleted.
resource_deprecated 404 An attempt was made to access a deprecated resource.
resource_already_exists 409 An attempt was made to create a resource that exists. Change key elements of the request (for example, the name) before reattempting.
unsupported_content_type 415 The request body isn't formatted as a JSON object. Check your request body and Content-Type header before reattempting.
too_many_requests 429 Too many API requests were received. Either wait and try again or contact support to solve this issue.
client_closed_connection 499 The client terminated the connection before the server received the data. Try again or provide a smaller request.
unknown_error 500 This error is for miscellaneous API errors. This error is temporary and can be retried.
service_offline 503 The service is temporarily offline. Try again later.
gateway_timeout 504 The Gateway responded within the timeout period. Try again later.