Skip to content
Okta Identity Governance
/
/Principal Access

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
GET
/governance/api/v1/principal-access
curl -i -X GET \
  'https://okta-subdomain.pixtulate.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
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": [
    { … }
  ]
}