Entitlements and bundles

Entitlements and bundles, at /iam/governance/entitlements, let you name the finer-grained things an app tracks internally — a license tier, an internal role, a feature flag — and group them with groups and apps into one thing a person can ask for in a single request. Before using either, read the one thing that decides whether this feature does what you probably assume it does.

Creating an entitlement

An entitlement belongs to one app, named by app_id — the same operator-authored slug App assignments already uses, not a system id. It needs a name (1–160 characters) and can optionally carry external_value (the value the app itself uses internally for this entitlement, if you track one) and a free-text description.

POST /organizations/{orgID}/governance/entitlements
{ "app_id": "salesforce", "name": "Sales Cloud license", "external_value": "SFDC_SALES_LICENSE" }

A name must be unique per app: creating a second entitlement with the same name under the same app_id is refused with "an entitlement with this name already exists for this app." Deleting one does not touch any bundle that already references it — the bundle keeps the reference, and applying that bundle again will fail on the missing entitlement, which is worth knowing before you delete one that is actually in use.

Bundles: one requestable unit

A bundle groups entitlements, groups and apps — any mix of the three — into a single named thing, such as "New sales hire." Each item has an item_type of entitlement, group or app, and needs the matching id: an entitlement item needs entitlement_id, a group item needs group_id, and an app item needs both app_id and app_name (the display name, for the same reason a direct app request needs resource_label). A bundle needs at least one item; a name that collides with an existing bundle is refused with "a bundle with this name already exists."

The requestable flag decides whether the bundle shows up as something a person can ask for through access requests — set it off for a bundle an administrator only ever applies directly.

What applying a bundle actually does

Applying a bundle — whether through an approved access request or directly — walks its items and reuses the exact same grant machinery a direct assignment uses: a group item is added through the same group-membership call Groups and automatic membership documents, and an app item is assigned through the same call App assignments documents. An entitlement item has no grant call at all behind it — applying one only inserts a row recording that the person holds it, for exactly the reason the callout above explains.

Listing, viewing and removing

GET /organizations/{orgID}/governance/bundles?requestable=true filters to only the bundles a requester should be offered — this is exactly what the access-request form's bundle picker calls. GET .../bundles/{id} returns one bundle with its items resolved. Deleting a bundle removes the bundle and its item list; it does not revoke anything already granted from it — people who already hold its groups, apps or entitlement records keep them, the same as removing a group rule does not evict existing members.

Permissions

What to do next

1. Access requests and resource owners — how a requestable bundle is asked for and approved.
2. Separation of duties — before you bundle together groups that might conflict once granted.
3. App assignments and Groups and automatic membership — the direct-assignment mechanics a bundle item reuses.