Entitlement Bundles

Entitlement bundles allow you to grant multiple entitlements simultaneously to your users. Manage entitlement bundles with the following APIs.

See Entitlement Management for more information.

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

Creates an entitlement bundle

Request
Request Body schema: application/json
required

The writable attributes of an entitlement bundle

required
Array of objects

Collection of entitlements and associated value identifiers

name
required
string [ 1 .. 255 ] characters

The unique name of the entitlement bundle. This value can't be modified.

required
object

Representation of a resource

description
string [ 1 .. 1000 ] characters

The human readable description

Responses
201

A successful entitlement bundle 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/entitlement-bundles
Request samples
application/json

Request body for adding an entitlement bundle with one entitlement, one value

{
  • "name": "Salesforce admin bundle",
  • "description": "A bundle for full administrative access in salesforce",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "entitlements": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "values": [
        ]
      }
    ]
}
Response samples
application/json

Entitlement Bundle with one entitlement and one value

{
  • "id": "enbo3j1lwErh6dn701d6",
  • "name": "Github admin bundle",
  • "description": "Github bundle for administrative access",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "status": "ACTIVE",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:github:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "entitlements": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "values": [
        ]
      }
    ],
  • "_links": {}
}

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

Lists all or a subset of entitlement-bundles in your organization

Request
query Parameters
after
string <entitlement-bundle-id> = 20 characters

The after cursor provided by a prior request.

filter
string <scim-filter>

Apply various filters by using supported entitlement-bundles filtering properties.

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

Examples:
Query param: ?filter=lastUpdated gt "2022-05-24T14:15:22Z"
filter=lastUpdated%20gt%20%222022-05-24T14%3A15%3A22Z%22
Query param: ?filter=lastUpdated ge "2022-05-24T14:15:22Z" AND id gt "0bbfxqCAJWWGELFTYBBB"
filter=lastUpdated%20ge%20%222022-05-24T14%3A15%3A22Z%22%20AND%20id%20gt%20%220bbfxqCAJWWGELFTYBBB%22
Query param: ?filter=lastUpdated gt "2022-05-24T14:15:22Z" OR (lastUpdated ge "2022-05-24T14:15:22Z" AND id gt "0bbfxqCAJWWGELFTYBBB")
filter=lastUpdated%20gt%20%222022-05-24T14%3A15%3A22Z%22%20OR%20(lastUpdated%20ge%20%222022-05-24T14%3A15%3A22Z%22%20AND%20id%20gt%20%220bbfxqCAJWWGELFTYBBB%22)
Query param: ?filter=target.externalId eq "0oafxqCAJWWGELFTYASJ" AND target.type eq "APPLICATION"
filter=target.externalId%20eq%20%220oafxqCAJWWGELFTYASJ%22%20AND%20target.type%20eq%20%22APPLICATION%22
Query param: ?filter=targetResourceOrn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ"
filter=targetResourceOrn%20eq%20%22orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ%22
Query param: ?filter=status eq "ACTIVE"
filter=status%20eq%20%22ACTIVE%22
Query param: ?filter=name sw "sales"
filter=name%20sw%20%22sales%22
include
Array of strings

The include filter adds additional properties that are available in the retrieve an entitlement bundle operation, but are omitted from the list response normally.

Items Value: "full_entitlements" Examples:
Query param: ?include=full_entitlements
include=full_entitlements
limit
integer [ 1 .. 200 ]
Default: 20

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

orderBy
string <order-by>

Apply an ordering of entitlement-bundles by specifying a supported entitlement bundle property name with %20asc or %20desc suffix.

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

Examples:
Query param: ?orderBy=created desc
orderBy=created%20desc
Query param: ?orderBy=lastUpdated desc
orderBy=lastUpdated%20desc
Query param: ?orderBy=lastUpdated asc,id asc
orderBy=lastUpdated%20asc%2Cid%20asc
Responses
200

A successful entitlement bundle 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/entitlement-bundles
Request samples 
Response samples 
application/json
A list of entitlement bundle with no filter


{}
Retrieve an entitlement bundle
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.read
Retrieves the full representation of a entitlement bundle


Request 
path Parameters
entitlementBundleId
required
string
The id of the entitlement bundle


 
query Parameters
include
Array of strings
The include filter adds additional properties that are available in the retrieve an entitlement bundle operation, but are omitted from the list response normally.


Items Value: "full_entitlements"   Examples: 
Query param: ?include=full_entitlements 
include=full_entitlements
Responses 
200
A successful entitlement bundle get 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/entitlement-bundles/{entitlementBundleId}
Request samples 
Response samples 
application/json
Entitlement Bundle with one entitlement and one value


{
  • "id": "enbo3j1lwErh6dn701d6",
  • "name": "Github admin bundle",
  • "description": "Github bundle for administrative access",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "status": "ACTIVE",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:github:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "entitlements": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "values": [
        ]
      }
    ],
  • "_links": {}
}
Replace an entitlement bundle
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage
Replaces an entitlement bundle's name, description or entitlements.


Entitlement updates will be applied to existing grants referencing this bundle and may change principal entitlements.


Request 
path Parameters
entitlementBundleId
required
string
The id of the entitlement bundle


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


required
object
Links available on a single entitlement bundle representation


 
id
required
string  non-empty 
Unique identifier for the object


 
name
required
string  [ 1 .. 255 ] characters 
The unique name of the entitlement bundle. This value can't be modified.


 
status
required
string
An entitlement bundle has a status lifecycle described in our entitlement bundle lifecycle documentation.


An entitlement bundle has a status of ACTIVE after creation.


When the bundle is deleted, it transitions to a status of DELETED.


At some point in the future, the bundle will be purged entirely. At that point in time, the bundle will no longer be included in list operations, and get operations return a 404.


 Enum: "ACTIVE" "DELETED"  
required
object
Representation of a resource


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


See the supported-resources endpoint for reference


 
description
string  [ 1 .. 1000 ] characters 
The human readable description


 
Array of objects
Collection of entitlements and associated value identifiers


 
Responses 
200
A successful entitlement bundle update response


400
An invalid request to create an entitlement bundle


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


put/governance/api/v1/entitlement-bundles/{entitlementBundleId}
Request samples 
application/json
Entitlement bundle with multiple entitlements values


{
  • "id": "enbogpaj3XUzcM62u1d6",
  • "name": "Github admin bundle",
  • "description": "Github bundle for administrative access",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "status": "ACTIVE",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:github:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "entitlements": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "values": [
        ]
      }
    ],
  • "_links": {}
}
Response samples 
application/json
Entitlement Bundle with one entitlement and one value


{
  • "id": "enbo3j1lwErh6dn701d6",
  • "name": "Github admin bundle",
  • "description": "Github bundle for administrative access",
  • "created": "2022-05-24T14:15:22Z",
  • "createdBy": "00ub0oNGTSWTBKOLGLNR",
  • "lastUpdated": "2022-05-24T14:15:22Z",
  • "lastUpdatedBy": "00ub0oNGTSWTBKOLGLNR",
  • "status": "ACTIVE",
  • "targetResourceOrn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:github:0oafxqCAJWWGELFTYASJ",
  • "target": {
    • "externalId": "0oafxqCAJWWGELFTYASJ",
    • "type": "APPLICATION"
    },
  • "entitlements": [
    • {
      • "id": "espo3v6xlwdtEX2il1d6",
      • "values": [
        ]
      }
    ],
  • "_links": {}
}
Delete an entitlement bundle
Beta
Admin permissions required: Application Administrator
OAuth 2.0: okta.governance.entitlements.manage
Deletes a entitlement bundle


Request 
path Parameters
entitlementBundleId
required
string
The id of the entitlement bundle


 
Responses 
204
A successful entitlement bundle delete response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


409
An invalid request due to status conflict when deleting a entitlement bundle


429
When the rate limit has been exceeded


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


delete/governance/api/v1/entitlement-bundles/{entitlementBundleId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}