Skip to content
Okta Identity Governance
/
Management APIs
/
/
Retrieve an entitlement h...

Retrieve an entitlement history

Request

OAuth 2.0 scope:
  • 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.

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

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 by a principal user and an app resource
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND princip
Filter by a principal user and an app resource ORNs
filter=resourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND principalOrn eq "orn:okta:directory:00o11edPwGqbUrsDm0g4:
Filter by a principal user, an app, and a start date
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND princip
Filter by a principal user, an app, and an end date
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND princip
Filter by a principal user, an app, and a date range
filter=resource.externalId eq "0oafxqCAJWWGELFTYASJ" AND resource.type eq "APPLICATION" AND principal.externalId eq "00ub0oNGTSWTBKOLGLNR" AND princip
Filter by a principal user and an app ORNs with a date range
filter=resourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" AND principalOrn eq "orn:okta:directory:00o11edPwGqbUrsDm0g4:
Filter by principal and resource IDs
filter=resourceId eq "res503IOSVGTK5Jwx0g3" AND principalId eq "pri52knJhV4kPqp9j0g3"
limitinteger, [ 1 .. 100 ]

The maximum number of records returned in a response

Default:20
afterstring

Specifies the pagination cursor for the next page of results. Treat this as an opaque value obtained through the standard link headers. See pagination.

Example:after=00u68w6vzKLultXS97g6
includeArray of strings

An optional parameter that adds additional properties in the metadata response object

Items ValueDescription
counts

Includes a count of entitlement history records in the metadata.total response

Example:include=counts
GET
/governance/api/v1/principal-entitlements/history
curl -i -X GET \
  'https://okta-subdomain.pixtulate.com/governance/api/v1/principal-entitlements/history?filter=resource.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20resource.type%20eq%20%22APPLICATION%22%20AND%20principal.externalId%20eq%20%2200ub0oNGTSWTBKOLGLNR%22%20AND%20principal.type%20eq%20%22OKTA_USER%22&limit=20&after=00u68w6vzKLultXS97g6&include=counts'

Responses

A successful principal entitlements history response

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
resourceOrnstring, (okta-resource-orn)(resource-orn)

The Okta resource in ORN format

See the ORN format for supported resources.

resourceobject(target-resource)

Representation of a resource

principalOrnstring, (okta-user-orn)(user-orn)

The Okta user in ORN format

Example:"orn:okta:directory:00o8rk36Bp5eZKOrw0g4:users:00u1ktfFMZ5HNoj7k0g4"
principalobject(target-principal-full)

Representation of a principal

entitlementHistoryArray of objects, [ 0 .. 100 ] items(entitlement-history-record)

Principal entitlements history list

metadataobject(list-metadata)

Metadata for the list response

Response
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": [
    { … },
    { … },
    { … }
  ],
  "_links": {
    "self": { … },
    "next": { … }
  },
  "metadata": {
    "total": 4
  }
}