Replace an entitlement

Okta Identity Governance

Management APIs

Request

okta.governance.entitlements.manage

APP_ADMIN

Replaces an entitlement's name, description, or values. This API requires a complete list of updated values, which may present limitations for certain use cases. For more practical and flexible usage, consider using the Update the entitlement.

Path

entitlementIdstringrequired

Unique identifier for the entitlement

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 Value	Description
string	The entitlement property is a single value.
array	The entitlement property is multivalued.

idstring, non-emptyrequired

Unique identifier for 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-updatable)required

Collection of entitlement values for update operations.

Example:

[
  {
    "name": "my-object-1",
    "description": "The unique instance of my-object-1"
  }
]

PUT

/governance/api/v1/entitlements/{entitlementId}

curl -i -X PUT \
  'https://okta-subdomain.pixtulate.com/governance/api/v1/entitlements/{entitlementId}' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "esp2lr1lavoGDYw5U8g6",
    "name": "License Entitlement",
    "externalValue": "license_entitlement",
    "description": "Entitlement description",
    "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
    "parent": {
      "externalId": "0oafxqCAJWWGELFTYASJ",
      "type": "APPLICATION"
    },
    "multiValue": true,
    "dataType": "string",
    "values": [
      {
        "id": "ent148gF8aZoRfFsh0g4",
        "name": "value1",
        "description": "description for value1",
        "externalValue": "value_1",
        "orn": "orn:okta:governance:00o11edPwGqbUrsDm0g4:entitlement-values:ent148gF8aZoRfFsh0g4"
      },
      {
        "id": "entotuwr1z1efm5RA1d6",
        "name": "value2",
        "description": "new value for entitlement",
        "externalValue": "value_2",
        "orn": "orn:okta:governance:00o11edPwGqbUrsDm0g4:entitlement-values:entotuwr1z1efm5RA1d6"
      }
    ]
  }'

Responses

A successful entitlement update 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 Value	Description
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

_linksobject(entitlement-links)

Links to related resources

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 successful entitlement update

{
  "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,
  "dataType": "string",
  "required": false,
  "values": [
    { … },
    { … }
  ],
  "_links": {
    "self": { … },
    "values": { … }
  },
  "metadata": {
    "total": 2
  }
}