Entitlements

An entitlement is a permission that allows users to take specific actions within a resource, such as an application. Manage entitlements and values with the following APIs.

See Entitlement Management for more information.

Create an entitlement
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage

Creates a new entitlement

Request
Request Body schema: application/json
required

The writable attributes of an entitlement

dataType
required
string

The data type of the entitlement property. If the entitlement property is multivalued, the data type is replaced with an array.

Enum: "array" "string"
externalValue
required
string [ 1 .. 255 ] characters

The value of an entitlement property

multiValue
required
boolean

The property that determines if the entitlement property can hold multiple values. If this is set to true, the data type is replaced with an array.

name
required
string [ 1 .. 255 ] characters

The display name for an entitlement property

required
object

Representation of a resource

required
Array of objects <= 1000 items
description
string [ 1 .. 1000 ] characters

The description of an entitlement property

Responses
201

A successful entitlement creation operation

400

An invalid request to create or update an entitlement

401

When authentication fails

403

When authorization fails

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

post/governance/api/v1/entitlements
Request samples
application/json

Request body for adding an entitlement

{
  • "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"
      }
    ]
}
Response samples
application/json

Response for a successful entitlement creation

{
  • "id": "esp2lr1lavoGDYw5U8g6",
  • "name": "License Entitlement",
  • "externalValue": "license_entitlement",
  • "description": "Some license entitlement",
  • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "parent": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "multiValue": true,
  • "required": false,
  • "dataType": "string",
  • "values": [
    • {
      • "id": "ent148fuJDGTsvYjP0g4",
      • "name": "value1",
      • "description": "description for value1",
      • "externalValue": "value_1"
      },
    • {
      • "id": "ent148gF8aZoRfFsh0g4",
      • "name": "value2",
      • "description": "description for value2",
      • "externalValue": "value_2"
      }
    ],
  • "_links": {},
  • "metadata": {
    • "total": 2
    }
}

List all entitlements
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read

Lists all entitlements specific to a resource

Request
query Parameters
after
string

The after cursor provided by a prior request.

filter
required
string <scim-filter>

Apply various filters by using supported entitlements filtering properties. Resource filter is required before any other supported filtering.

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

Examples:
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION"
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22
Query param: ?filter=parentResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ"
filter=parentResourceOrn%20eq%20%22orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ%22
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND name sw "License"
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22%20AND%20name%20sw%20%22License%22
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND (id eq "espfxqCAJWWGELFTYASJ" OR id eq "espfxqCAJWWGELFTYASI")
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22%20AND%20%28id%20eq%20%22espfxqCAJWWGELFTYASJ%22%20OR%20id%20eq%20%22espfxqCAJWWGELFTYASI%22%29
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND externalValue eq "License"
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22%20AND%20externalValue%20eq%20%22License%22
limit
integer [ 1 .. 200 ]
Default: 20

The maximum number of records that will be returned in a given result.

orderBy
Array of strings = 1 items
Default: ["name asc"]

A field by which results can be sorted. For now, sorting by a single field is supported.

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

Examples:
Query param: ?orderBy=name asc
orderBy=name%20asc
Query param: ?orderBy=created desc
orderBy=created%20desc
Responses
200

A successful entitlements list response

400

An invalid request to list entitlement-bundles

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/entitlements
Request samples 
Response samples 
application/json
A list of entitlements


{}
Delete an entitlement
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage
Deletes entitlement


Request 
path Parameters
entitlementId
required
string
The id of the entitlement


 
Responses 
204
A successful entitlement delete response


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


delete/governance/api/v1/entitlements/{entitlementId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}
Retrieve an entitlement
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read
Retrieves a single entitlement


Request 
path Parameters
entitlementId
required
string
The id of the entitlement


 
Responses 
200
A successful entitlements list response


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/entitlements/{entitlementId}
Request samples 
Response samples 
application/json
Retrieve an entitlement response


{}
Replace an entitlement
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage
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.


Request 
path Parameters
entitlementId
required
string
The id of the entitlement


 
Request Body schema: application/json
required
The writable attributes of an entitlement


dataType
required
string
The data type of the entitlement property. If the entitlement property is multivalued, the data type is replaced with an array.


 Enum: "array" "string"  
externalValue
required
string  [ 1 .. 255 ] characters 
The value of an entitlement property


 
id
required
string  = 20 characters 
The id of an entitlement property


 
multiValue
required
boolean
The property that determines if the entitlement property can hold multiple values. If this is set to true, the data type is replaced with an array.


 
name
required
string  [ 1 .. 255 ] characters 
The display name for an entitlement property


 
required
object
Representation of a resource


 
parentResourceOrn
required
string <okta-resource-orn> 
The Okta App instance id in ORN format


See the supported-resources endpoint for reference


 
required
Array of objects  <= 1000 items 
Collection of entitlement values.


 
object
Links available in list response


 
description
string  [ 1 .. 1000 ] characters 
The description of an entitlement property


 
object
Metadata for the list response


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


 
Responses 
200
A successful entitlement update operation


400
An invalid request to create or update an entitlement


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


put/governance/api/v1/entitlements/{entitlementId}
Request samples 
application/json
Request body for updating an entitlement


{
  • "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"
      },
    • {
      • "id": "entotuwr1z1efm5RA1d6",
      • "name": "value2",
      • "description": "new value for entitlement",
      • "externalValue": "value_2"
      }
    ]
}
Response samples 
application/json
Response for successful entitlement update


{
  • "id": "esp2lr1lavoGDYw5U8g6",
  • "name": "License Entitlement",
  • "externalValue": "license_entitlement",
  • "description": "Some license entitlement",
  • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "parent": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "multiValue": true,
  • "dataType": "string",
  • "required": false,
  • "values": [
    • {
      • "id": "ent148gF8aZoRfFsh0g4",
      • "name": "Updated value1",
      • "description": "description for value1",
      • "externalValue": "value_1"
      },
    • {
      • "id": "ent148fuJDGTsvYjP0g4",
      • "name": "Updated value2",
      • "description": "description for value2",
      • "externalValue": "value_2"
      }
    ],
  • "_links": {},
  • "metadata": {
    • "total": 2
    }
}
Update the entitlement
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage
Updates an entitlement name, description or a particular value property. The values array in the response contains only the updated entitlement values. No entitlement values are returned if the name and description is updated or values are only removed in the update.


Request 
path Parameters
entitlementId
required
string
The id of the entitlement


 
Request Body schema: application/json
required
The writable attributes of an entitlement.


 Array ([ 1 .. 100 ] items)
op
required
string  non-empty 
The operation to be performed for update.


 Enum: "ADD" "REMOVE" "REPLACE"  
path
required
string
The path of the property being updated. ex - /values/{id} for REMOVE, REPLACE and /values/- for ADD for entitlement value update.


 
refType
required
string
 
object
 
Responses 
200
A successful entitlement update operation


400
An invalid request to create or update an entitlement


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


patch/governance/api/v1/entitlements/{entitlementId}
Request samples 
application/json
Request body for updating entitlement


[
  • {
    • "op": "ADD",
    • "path": "/values/-",
    • "value": {
      • "name": "value1",
      • "description": "description for value1",
      • "externalValue": "value_1"
      },
    • "refType": "ENTITLEMENT-VALUE"
    },
  • {
    • "op": "REMOVE",
    • "path": "/values/ent148gF8aZoRfFsh0g4",
    • "refType": "ENTITLEMENT-VALUE"
    },
  • {
    • "op": "REPLACE",
    • "path": "/values/ent148gF8aZoRfFsh0g4",
    • "value": {
      • "name": "value1",
      • "description": "replace description for value1"
      },
    • "refType": "ENTITLEMENT-VALUE"
    },
  • {
    • "op": "ADD",
    • "path": "/description",
    • "value": "add description for entitlement",
    • "refType": "ENTITLEMENT"
    },
  • {
    • "op": "REMOVE",
    • "path": "/description",
    • "refType": "ENTITLEMENT"
    },
  • {
    • "op": "REPLACE",
    • "path": "/description",
    • "value": "replace description for entitlement",
    • "refType": "ENTITLEMENT"
    },
  • {
    • "op": "REPLACE",
    • "path": "/name",
    • "value": "replace name for entitlement",
    • "refType": "ENTITLEMENT"
    }
]
Response samples 
application/json
Response for successful entitlement update


{
  • "id": "esp2lr1lavoGDYw5U8g6",
  • "name": "License Entitlement",
  • "externalValue": "license_entitlement",
  • "description": "Some license entitlement",
  • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "parent": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "multiValue": true,
  • "dataType": "string",
  • "required": false,
  • "values": [
    • {
      • "id": "ent148gF8aZoRfFsh0g4",
      • "name": "Updated value1",
      • "description": "description for value1",
      • "externalValue": "value_1"
      },
    • {
      • "id": "ent148fuJDGTsvYjP0g4",
      • "name": "Updated value2",
      • "description": "description for value2",
      • "externalValue": "value_2"
      }
    ],
  • "_links": {},
  • "metadata": {
    • "total": 2
    }
}
List all values for an entitlement
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read
Lists all values for an entitlement


Request 
path Parameters
entitlementId
required
string
The id of the entitlement


 
query Parameters
after
string
The after cursor provided by a prior request.


 
filter
string <scim-filter> 
Apply various filters by using supported entitlement values filtering properties.


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


  Examples: 
Query param: ?filter=name sw "License" 
filter=name%20sw%20%22License%22
limit
integer  [ 1 .. 200 ] 
 Default:  20
The maximum number of records that will be returned in a given result.


 
orderBy
Array of strings  = 1 items 
 Default:  ["name asc"]
A field by which results can be sorted. For now, sorting by a single field is supported.


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


  Examples: 
Query param: ?orderBy=name asc 
orderBy=name%20asc
Query param: ?orderBy=created desc 
orderBy=created%20desc
Responses 
200
A successful list of entitlement values response


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/entitlements/{entitlementId}/values
Request samples 
Response samples 
application/json
A list of entitlement values


{
  • "data": [
    • {
      • "id": "entfxqCAJWWGELFTYAAA",
      • "name": "Admin access",
      • "description": "ability to grant an access",
      • "externalValue": "admin",
      • "entitlementId": "esp5zFLCIUV7Vibro0g2",
      • "externalId": "75941239-123s-1245-xyz6-562fee27167r",
      • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
      • "parent": {
        }
      },
    • {
      • "id": "entfxqCAJWWFTFUUYBBB",
      • "name": "Corporate License",
      • "description": "Corporate License",
      • "externalValue": "corporate",
      • "entitlementId": "esp81PLbVQGWaklZb0g2",
      • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
      • "parent": {
        }
      }
    ],
  • "_links": {},
  • "metadata": {
    • "total": 2
    }
}
Retrieve an entitlement value
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read
Retrieves a single entitlement value


Request 
path Parameters
entitlementId
required
string
The id of the entitlement


 
valueId
required
string
The id of the entitlement value


 
Responses 
200
A successful entitlement value response


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/entitlements/{entitlementId}/values/{valueId}
Request samples 
Response samples 
application/json
Entitlement value data


{
  • "id": "entfxqCAJWWGELFTYAAA",
  • "name": "Admin access",
  • "description": "ability to grant an access",
  • "externalValue": "admin",
  • "entitlementId": "esp5zFLCIUV7Vibro0g2",
  • "externalId": "75941239-123s-1245-xyz6-562fee27167r",
  • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
  • "parent": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "_links": {}
}
List all entitlement values
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read
Lists all entitlement values


Request 
query Parameters
after
string
The after cursor provided by a prior request.


 
filter
required
string <scim-filter> 
Apply various filters by using supported entitlements filtering properties. Resource filter is required before any other supported filtering.


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


  Examples: 
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" 
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22
Query param: ?filter=parentResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ" 
filter=parentResourceOrn%20eq%20%22orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ%22
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND name sw "License" 
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22%20AND%20name%20sw%20%22License%22
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND (entitlementId eq "espfxqCAJWWGELFTYASJ" OR entitlementId eq "espfxqCAJWWGELFTYASI") 
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22%20AND%20%28entitlementId%20eq%20%22espfxqCAJWWGELFTYASJ%22%20OR%20entitlementId%20eq%20%22espfxqCAJWWGELFTYASI%22%29
Query param: ?filter=parent.externalId eq "0oafxqCAJWWGELFTYASJ" AND parent.type eq "APPLICATION" AND externalValue eq "corporate" 
filter=parent.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20parent.type%20eq%20%22APPLICATION%22%20AND%20externalValue%20eq%20%22corporate%22
limit
integer  [ 1 .. 200 ] 
 Default:  200
The maximum number of records that will be returned in a given result.


 
orderBy
Array of strings  = 1 items 
 Default:  ["id asc"]
A field by which results can be sorted. For now, sorting by a single field is supported.


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


  Examples: 
Query param: ?orderBy=name asc 
orderBy=name%20asc
Query param: ?orderBy=id desc 
orderBy=id%20desc
Responses 
200
A successful list of entitlement values response


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/entitlements/values
Request samples 
Response samples 
application/json
A list of entitlement values


{
  • "data": [
    • {
      • "id": "entfxqCAJWWGELFTYAAA",
      • "name": "Admin access",
      • "description": "ability to grant an access",
      • "externalValue": "admin",
      • "entitlementId": "esp5zFLCIUV7Vibro0g2",
      • "externalId": "75941239-123s-1245-xyz6-562fee27167r",
      • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
      • "parent": {
        }
      },
    • {
      • "id": "entfxqCAJWWFTFUUYBBB",
      • "name": "Corporate License",
      • "description": "Corporate License",
      • "externalValue": "corporate",
      • "entitlementId": "esp81PLbVQGWaklZb0g2",
      • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:salesforce:0oafxqCAJWWGELFTYASJ",
      • "parent": {
        }
      }
    ],
  • "_links": {},
  • "metadata": {
    • "total": 2
    }
}