Principal Access

Principal Access represent a summary of user access for a resource

See Entitlement Management for more information.

Retrieve the principal access for a resource
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read

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.

Request
query Parameters
filter
required
string <scim-filter>

Apply various filters by using supported principal access filtering properties.

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

Examples:
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND targetPrincipal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND targetPrincipal.type eq "OKTA_USER"
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
Query param: ?filter=parentResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND targetPrincipalOrn eq "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR"
filter=parentResourceOrn%20eq%20%22orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ%22%20AND%20targetPrincipalOrn%20eq%20%22orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR%22
Responses
200

Principal access for a specific resource.

400

An invalid list request

401

When authentication fails

403

When authorization fails

404

When the requested resource was not found

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

get/governance/api/v1/principal-access
Request samples 
Response samples 
application/json
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": [
    • {
      • "grantType": "ENTITLEMENT-BUNDLE",
      • "grantMethod": "ACCESS_REQUEST",
      • "startTime": "2024-03-15T00:00:00Z",
      • "expirationTime": "2024-04-30T23:59:59Z",
      • "timeZone": "America/Toronto",
      • "grant": {},
      • "bundle": {
        },
      • "entitlements": [
        ]
      }
    ]
}