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: Entitlement 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

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

name
required
string [ 1 .. 255 ] characters

The display name for an entitlement property

required
object

Representation of a resource

required
Array of objects
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 a 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 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,
  • "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"
      }
    ]
}

List all entitlements
Beta
Admin permissions required: Entitlement 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
Entitlement data


{
  • "id": "espfxqCAJWWGELFTYASJ",
  • "name": "Role",
  • "externalValue": "Role",
  • "description": "This is a role entitlement",
  • "multiValue": true,
  • "required": false,
  • "dataType": "string",
  • "parentResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ",
  • "parent": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION",
    • "name": "Salesforce"
    },
  • "values": [
    • {
      • "id": "entfxqCAJWWGELFTYAAA",
      • "name": "Admin access",
      • "description": "ability to grant an access",
      • "externalValue": "admin"
      }
    ],
  • "_links": {},
  • "metadata": {
    • "total": 1
    }
}
Replace an entitlement
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage
Replaces an 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


 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


 
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


 
object
Links available in entitlements list response


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


 
object
Metadata describing the entitlement


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


 
Array of objects  [ 1 .. 1000 ] characters 
Collection of entitlement values


 
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 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"
      },
    • {
      • "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",
  • "values": [
    • {
      • "id": "ent148gF8aZoRfFsh0g4",
      • "name": "value1",
      • "description": "description for value1",
      • "externalValue": "value_1"
      },
    • {
      • "id": "ent148fuJDGTsvYjP0g4",
      • "name": "value2",
      • "description": "description for value2",
      • "externalValue": "value_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


{}
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


{}