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.
\nThis site documents API operations for Okta Privileged Access. For more documentation, see Okta Privileged Access.
\nMost operations require an HTTP Authorization header with a value of Bearer AUTH_TOKEN.
To retrieve a Bearer authentication token for API access:
\nkey_id\n and your API token in \nkey_secret\n.\nThe response from a successful Issue a service user token request provides you with a Bearer auth token (bearer_token) for OPA API authentication and the time the token expires (expires_at). It also returns the tenant that's applicable to your Bearer auth token (team_name).
If you get a 401 Unauthorized response code from an OPA API request, it's most likely that your Bearer auth token expired. Use the Issue a service user token request again to obtain a new Bearer auth token. Also be mindful of your service user's API key expiry time.
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.
\n| Role | \nDescription | \n
|---|---|
pam_admin | \nThis role allows a user to assign other administrative roles to OPA Groups and Users | \n
resource_admin | \nThis 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. | \n
delegated_resource_admin | \nThis role allows a user to manage all Projects within their assigned Resource Groups | \n
security_admin | \nThis 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. | \n
delegated_security_admin | \nThis role allows a user to create Security Policies that control access to resources within their assigned Resource Groups | \n
end_user | \nThis 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. | \n
Requests that return lists of objects may support pagination. By default, pagination limits the number of returned objects in a given response to 100.
\nOPA provides information about pagination in Link headers:
rel=\"next\"\n indicates that a subsequent page is available and contains the URL used to fetch it.\nrel=\"prev\"\n indicates that a previous page is available and contains the URL used to fetch it.\nTo fetch a full list of resources, Clients should use the following approach when retrieving lists:
\nlist\n.\nrel=\"next\"\n. If such a value exists, fetch it and repeat steps two and three.\nAn example of a paginated request that contains the URL from the rel=\"next\" Link header:
curl -v -X GET \\\n-H \"Authorization: Bearer {jwt}\" \\\nhttps://{org}.pam.okta.com/v1/teams/{team_name}/groups?offset={next_page_offset}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.
\nAn example of a paginated response body that contains a list field:
{\n \"list\": [\n {\n \"id\": \"5dfc51da-3991-4330-88bf-ef710a7d53e5\",\n \"name\": \"everyone\",\n \"roles\": [\n \"end_user\",\n ],\n \"deleted_at\": null\n },\n {\n \"id\": \"ad2ff761-83da-4769-b86c-85042eefc1d7\",\n \"name\": \"owners\",\n \"roles\": [\n \"pam_admin\"\n ],\n \"deleted_at\": null\n }\n ]\n}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:
\n| Header | \nDescription | \n
|---|---|
X-RateLimit-Limit | \nA value that indicates the total number of operations permitted per rate limit period | \n
X-RateLimit-Remaining | \nA value that indicates the total number of remaining operations permitted during the current rate limit period | \n
X-RateLimit-Reset | \nA unix timestamp that indicates when the number of rate limit requests fully replenishes | \n
X-RateLimit-Retry-At | \nA 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 | \n
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:
\n| Error | \nCode | \nDescription | \n
|---|---|---|
invalid_request | \n400 | \nThis error is returned on an improper or invalid request body. The request should be modified before being reattempted. | \n
authentication_error | \n401 | \nA correct API token wasn't provided. A new token should be retrieved before reattempting. | \n
authorization_error | \n401 | \nThe current User doesn't have permission to access the resource requested. Occasionally, this is the result of expired permissions and requires reauthentication. | \n
server_authorization_revoked | \n401 | \nA previously deleted Server attempted to reconnect with its old token. Re-enroll the Server to remedy this error. | \n
forbidden_error | \n403 | \nA User requests a resource that they don't have access to. | \n
quota_exceeded | \n403 | \nA Team exceeded the allotted resource type. Contact support to increase your quota. | \n
disabled_team | \n403 | \nThe OPA Team that is being accessed is disabled. Contact support to resolve this issue. | \n
resource_does_not_exist | \n404 | \nA resource doesn't exist. Most likely the path parameters of the URL are incorrectly spelled or the specific resource was deleted. | \n
resource_deprecated | \n404 | \nAn attempt was made to access a deprecated resource. | \n
resource_already_exists | \n409 | \nAn attempt was made to create a resource that exists. Change key elements of the request (for example, the name) before reattempting. | \n
unsupported_content_type | \n415 | \nThe request body isn't formatted as a JSON object. Check your request body and Content-Type header before reattempting. | \n
too_many_requests | \n429 | \nToo many API requests were received. Either wait and try again or contact support to solve this issue. | \n
client_closed_connection | \n499 | \nThe client terminated the connection before the server received the data. Try again or provide a smaller request. | \n
unknown_error | \n500 | \nThis error is for miscellaneous API errors. This error is temporary and can be retried. | \n
service_offline | \n503 | \nThe service is temporarily offline. Try again later. | \n
gateway_timeout | \n504 | \nThe Gateway responded within the timeout period. Try again later. | \n