Overview

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.

Authentication

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.

Permissions

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

Pagination

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}" \
https://{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.

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

{
  "list": [
    {
      "id": "5dfc51da-3991-4330-88bf-ef710a7d53e5",
      "name": "everyone",
      "roles": [
        "end_user",
      ],
      "deleted_at": null
    },
    {
      "id": "ad2ff761-83da-4769-b86c-85042eefc1d7",
      "name": "owners",
      "roles": [
        "pam_admin"
      ],
      "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:

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

Errors

Okta Privileged Access returns the following HTTP errors: