Principal Entitlements

Principal Entitlements represent the effective entitlements for a user and resource after evaluating all grants.

See Entitlement Management for more information.

Retrieve the principal's effective entitlements for a resource
OAuth 2.0 scopes:
  • okta.governance.entitlements.read
Admin roles:
  • APP_ADMIN

Retrieves the principal's effective entitlements for a specific resource

Request
query Parameters
filter
required
string <scim-filter>

Apply various filters by using supported principal entitlements 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

List of all principal entitlements for a specific resource.

400

An invalid list request

401

When authentication fails

403

When authorization fails

404

When the requested resource wasn't 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-entitlements
Request samples 
Response samples 
application/json
When a user has been granted some License and Role entitlement's to Salesforce


{
  • "data": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "name": "License",
      • "externalValue": "License",
      • "description": "This is a license entitlement",
      • "multiValue": true,
      • "required": false,
      • "dataType": "string",
      • "targetPrincipalOrn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR",
      • "targetPrincipal": {
        },
      • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
      • "parent": {
        },
      • "values": [
        ]
      },
    • {
      • "id": "esp4rg7fkom0c3AsX8g6",
      • "name": "Role",
      • "externalValue": "Role",
      • "description": "This is a role entitlement",
      • "multiValue": false,
      • "required": false,
      • "dataType": "string",
      • "targetPrincipal": {
        },
      • "parent": {
        },
      • "values": [
        ]
      }
    ]
}
Retrieve an entitlement history
Beta
OAuth 2.0 scopes: 
  • okta.governance.entitlements.read
Admin roles: 
  • APP_ADMIN
Retrieves an entitlement history log for a specific principal and resource.


Specify the required principal and resource references in the filter query parameter.
You can optionally specify a time range for the returned history log.


Request 
query Parameters
after
string
The pagination cursor that points to the last record of the previous request.


 
 Example:  after=00u68w6vzKLultXS97g6
filter
required
string <scim-filter> 
This filter expression supports the eq operator
and the following required and optional properties.


Required: You must specify both principal and resource references with one of these sets of properties:


    

  • principal.externalId, principal.type, resource.externalId, and resource.type
    • 

  • principalOrn and resourceOrn
    • 

  • principalId and resourceId
    • 



Optional: You can optionally filter by a date range with the following properties:


    

  • startDate: Start of the date range (inclusive) in ISO 8601 UTC format. If omitted, data is retrieved from the earliest available records.
    • 

  • endDate: End of the date range (inclusive) in ISO 8601 UTC format. If omitted, data is retrieved up to the current time.
    • 



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


  Examples: 
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND principal.type eq "OKTA_USER"
filter=resourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND principalOrn eq "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR"
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND principal.type eq "OKTA_USER" AND startDate eq "2024-01-01T00:00:00Z"
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND principal.type eq "OKTA_USER" AND endDate eq "2024-12-31T23:59:59Z"
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND principal.type eq "OKTA_USER" AND startDate eq "2024-01-01T00:00:00Z" AND endDate eq "2024-12-31T23:59:59Z"
filter=resourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND principalOrn eq "orn:okta:directory:00o11edPwGqbUrsDm0g4:users:00ub0oNGTSWTBKOLGLNR" AND startDate eq "2024-01-01T00:00:00Z" AND endDate eq "2024-12-31T23:59:59Z"
filter=resourceId eq "res503IOSVGTK5Jwx0g3" AND principalId eq "pri52knJhV4kPqp9j0g3"
include
Array of strings
An optional parameter that adds additional properties in the metadata response object


Items Value: Description
counts
Includes a count of entitlement history records in the metadata.total response


 
 Example:  include=counts
limit
integer  [ 1 .. 100 ] 
 Default:  20
The maximum number of records returned in a response


 
Responses 
200
A successful principal entitlements history response


400
An invalid list request


401
When authentication fails


403
When authorization fails


404
When the requested resource wasn't 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-entitlements/history
Request samples 
Response samples 
application/json
The response to a principal entitlements history request with a startDate, limit=3, and include=counts


{
  • "resourceOrn": "orn:okta:idp:00o1kq5LLpmbGnOtz0g4:apps:oidc_client:0oacvetsS5uY0gCzk0g4",
  • "resource": {
    • "externalId": "0oacvetsS5uY0gCzk0g4",
    • "type": "APPLICATION"
    },
  • "principalOrn": "orn:okta:directory:00o1kq5LLpmbGnOtz0g4:users:00u1rvrLNphg0QAmP0g4",
  • "principal": {
    • "externalId": "00u1rvrLNphg0QAmP0g4",
    • "type": "OKTA_USER"
    },
  • "entitlementHistory": [
    • {
      • "startDate": "2025-05-27T18:02:20Z",
      • "endDate": "",
      • "lifecycle": "ACTIVE",
      • "entitlements": [
        ]
      },
    • {
      • "startDate": "2025-05-27T17:46:06Z",
      • "endDate": "2025-05-27T18:02:20Z",
      • "lifecycle": "INACTIVE",
      • "entitlements": [
        ]
      },
    • {
      • "startDate": "2025-05-27T16:43:54Z",
      • "endDate": "2025-05-27T17:46:06Z",
      • "lifecycle": "INACTIVE",
      • "entitlements": [
        ]
      }
    ],
  • "_links": {},
  • "metadata": {
    • "total": 4
    }
}