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 an entitlement bundle

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
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"
      }
    ],
  • "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

Full 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 an entitlement bundle

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

{}