Skip to content
Okta Identity Governance
/
/Entitlements

Entitlements

The Entitlements API allows you to manage entitlements and their values. An entitlement is a permission that allows users to take specific actions within a resource, such as an app. See Entitlement Management in the product documentation.

Note: An app must have entitlement management enabled before it can be used as an entitlement resource. See Enable Entitlement management in the product documentation.

Operations

Create an entitlement

Request

OAuth 2.0 scope:
  • okta.governance.entitlements.manage
Admin roles:
  • APP_ADMIN

Creates a new entitlement

Note: An HTTP 404 Not Found error is returned for app entitlements that aren't enabled with entitlement management. See Enable Entitlement management.

Bodyapplication/jsonrequired

The writable attributes of an entitlement

namestring, [ 1 .. 255 ] characters(entitlement-property-display-name)required

The display name for an entitlement property

Example:"my-object-1"
externalValuestring, [ 1 .. 255 ] characters(entitlement-property-value)required

The value of an entitlement property

descriptionstring, [ 1 .. 1000 ] characters(entitlement-property-description)

The description of an entitlement property

Example:"The unique instance of my-object-1"
multiValueboolean(entitlement-property-multi-value)required

Indicates if the entitlement property can hold multiple values. If this property is true, then the dataType property is set to array.

dataTypestring(entitlement-property-datatype)required

The data type of the entitlement property

Enum ValueDescription
string

The entitlement property is a single value.

array

The entitlement property is multivalued.

parentobject(target-resource)required

Representation of a resource

valuesArray of objects(entitlement-value-writable-properties)required
Example:
[
  {
    "name": "my-object-1",
    "description": "The unique instance of my-object-1"
  }
]
POST
/governance/api/v1/entitlements
curl -i -X POST \
  https://okta-subdomain.pixtulate.com/governance/api/v1/entitlements \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "License Entitlement",
    "externalValue": "license_entitlement",
    "description": "Some license entitlement",
    "parent": {
      "externalId": "0oafxqCAJWWGELFTYASJ",
      "type": "APPLICATION"
    },
    "multiValue": true,
    "dataType": "string",
    "values": [
      {
        "name": "value1",
        "description": "description for value1",
        "externalValue": "value_1"
      },
      {
        "name": "value2",
        "description": "description for value2",
        "externalValue": "value_2"
      }
    ]
  }'

Responses

A successful entitlement creation operation

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
idstring, = 20 characters(entitlement-property-id)required

The id property of an entitlement

namestring, [ 1 .. 255 ] characters(entitlement-property-display-name)required

The display name for an entitlement property

externalValuestring, [ 1 .. 255 ] characters(entitlement-property-value)required

The value of an entitlement property

descriptionstring, [ 1 .. 1000 ] characters(entitlement-property-description)

The description of an entitlement property

multiValueboolean(entitlement-property-multi-value)required

Indicates if the entitlement property can hold multiple values. If this property is true, then the dataType property is set to array.

requiredboolean(entitlement-property-required)

The property that determines if the entitlement property is a required attribute

dataTypestring(entitlement-property-datatype)required

The data type of the entitlement property

Enum ValueDescription
string

The entitlement property is a single value.

array

The entitlement property is multivalued.

createdBystring, (okta-user-id), [ 1 .. 20 ] characters(created-by)read-onlyrequired

The id of the Okta user who created the resource

createdstring, (date-time)(created)read-onlyrequired

The ISO 8601 formatted date and time when the resource was created

lastUpdatedstring, (date-time)(last-updated)read-onlyrequired

The ISO 8601 formatted date and time when the object was last updated

lastUpdatedBystring, (okta-user-id), [ 1 .. 20 ] characters(last-updated-by)read-onlyrequired

The id of the Okta user who last updated the object

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

valuesArray of objects(entitlement-values-full)required

Collection of entitlement values

metadataobject(list-metadata)

Metadata for the list response

Response
Response for a successful entitlement creation
{
  "id": "esp2lr1lavoGDYw5U8g6",
  "name": "License Entitlement",
  "externalValue": "license_entitlement",
  "description": "Some license entitlement",
  "created": "2022-05-24T14:15:22Z",
  "createdBy": "00ub0oNGTSWTBKOLGLNR",
  "lastUpdated": "2022-05-24T14:15:22Z",
  "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  "parent": {
    "externalId": "0oafxqCAJWWGELFTYASJ",
    "type": "APPLICATION"
  },
  "multiValue": true,
  "required": false,
  "dataType": "string",
  "values": [
    { … },
    { … }
  ],
  "_links": {
    "self": { … },
    "values": { … }
  },
  "metadata": {
    "total": 2
  }
}