Principal Access

Principal Access represent a summary of user access for a resource

See Entitlement Management for more information.

Operations

Retrieve the principal access for a resource

Request

Beta

OAuth 2.0 scope:

okta.governance.entitlements.read

Admin roles:

APP_ADMIN

Retrieves the current state of principal access for a specific resource. API shows if user has permanent or timed based access to the application along with what entitlements are assigned to that user.

Query

filterstring, (scim-filter)(scim-filter)required

Apply various filters by using supported principal access filtering properties.

Note: Query parameter percent encoding is required. See Percent-encoding

Examples:

Filter by user and application

filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND targetPrincipal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND targe

Filter by user and application ORNs

filter=parentResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND targetPrincipalOrn eq "orn:okta:directory:00o11edPw

curl -i -X GET \
  'https://subdomain.okta.com/governance/api/v1/principal-access?filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22%20AND%20targetPrincipal.externalId%20eq%20%2200ub0oNGTSWTBKOLGLNR%22%20AND%20targetPrincipal.type%20eq%20%22OKTA_USER%22'

Responses

Principal access for a specific resource.

Headers

Linkstring

A link to self and next.

Note: next is only present if there's another page of results.

X-Rate-Limit-Limitinteger, >= 1required

The rate-limit ceiling for the current request

Example:60

X-Rate-Limit-Remaininginteger, >= 0required

The number of requests left for the current rate-limit window

Example:60

X-Rate-Limit-Resetinteger, >= 0required

The time when the rate limit resets, specified in UTC epoch time (in seconds)

Example:1609459200

Bodyapplication/json

parentResourceOrnstring, (okta-resource-orn)(resource-orn)required

The Okta resource in ORN format

See the ORN format for supported resources.

parentobject(target-resource)required

Representation of a resource

targetPrincipalOrnstring, (okta-user-orn)(user-orn)required

The Okta user in ORN format

Example:"orn:okta:directory:00o8rk36Bp5eZKOrw0g4:users:00u1ktfFMZ5HNoj7k0g4"

targetPrincipalobject(target-principal-full)required

Representation of a principal

expirationTimestring, (date-time)

The date on which the user access expires. Date in ISO 8601 format.

timeZonestring, [ 1 .. 64 ] characters

The time zone, in IANA format, for the end date of the user access.

baseobject(grant)

representation of a base grant

additionalArray of objects(grant)

Response

Principal access data with base (POLICY or CUSTOM) and any additional entitlements

{
  "targetPrincipalOrn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR",
  "targetPrincipal": {
    "externalId": "00ub0oNGTSWTBKOLGLNR",
    "type": "OKTA_USER"
  },
  "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  "parent": {
    "externalId": "0oafxqCAJWWGELFTYASJ",
    "type": "APPLICATION"
  },
  "expirationTime": "2024-05-31T23:59:59Z",
  "timeZone": "America/Toronto",
  "base": {
    "grantType": "POLICY",
    "grantMethod": "POLICY",
    "expirationTime": "2024-05-31T23:59:59Z",
    "grant": { … },
    "entitlements": [ … ]
  },
  "additional": [
    { … }
  ]
}