Skip to main content
An entitlement is one grantable unit of access on an app, such as a role, a license, a group membership, or an access right. When someone requests access in Lumos, they request an entitlement. The result is an account that holds that entitlement. Each entitlement belongs to exactly one app. entitlement_type_label names the kind of entitlement, such as Role, License, or Group. The app sets this label, so the values vary by app. Lumos has no fixed list of values.
The Entitlement object

​
Attributes

​
Overrides and inheritance

An entitlement belongs to an app, and several of its fields override the app’s settings. For the fields that inherit, null means the entitlement uses the app’s value, and a value overrides it. AppStore settings names two fields that don’t inherit. custom_approval_message_override is the clearest case. Null means requesters see the app’s post_approval_message. If you set it, this entitlement’s message replaces the app’s message for this entitlement only. The three workflow fields follow the same rule, but their names differ:
  • approval_workflow_override is explicitly an override of the app’s approval_workflow.
  • provisioning_workflow and deprovisioning_workflow are the entitlement’s own bindings. They take precedence over the app’s default_provisioning_workflow and default_deprovisioning_workflow. The word “default” in the app’s field names marks the app’s workflows as the fallback.
Each workflow field returns { "id": … } by default. Name it in expand to get the full workflow inline:
Each workflow field also has its own read and write endpoints, listed under Endpoints. Use those endpoints to change which workflow is bound. To make the entitlement use its app’s approval workflow again, call Remove Entitlement Approval Workflow Override. It returns 204 whether or not an override was bound, and it doesn’t delete the workflow.

​
AppStore settings

appstore_settings appears only when you expand it. Even then, the response omits it when the parent app isn’t in the AppStore or the entitlement has no AppStore settings. Every entitlement made with Create Entitlement has AppStore settings. A synced entitlement has them only if Lumos can grant and remove it through the app’s integration. Expanded, it has four fields, and two of them inherit: request_validation_webhook_uuid looks like the two override fields, but it doesn’t inherit. When it’s null, no webhook validates requests for this entitlement. The app’s webhook doesn’t apply. These settings also have their own endpoints. Get Entitlement AppStore Settings returns the full object, so you don’t need to expand the entitlement. Update Entitlement AppStore Settings is the only way to change the settings. It takes the fields that a read returns, and a field you omit keeps its value:

​
Creating, updating, and deleting

Create Entitlement takes app_id and label, and creates a requestable entitlement on that app, which people can request from the AppStore. It also takes description_override and custom_approval_message_override, which set the entitlement’s description and post-approval message in the same call:
Configure everything else after you create the entitlement. Set its workflows with the workflow endpoints, and its AppStore settings with Update Entitlement AppStore Settings. An entitlement created with POST has visible_in_appstore set to true. If its app is in the AppStore, everyone allowed to request that app sees the entitlement in the catalog and can request it immediately. POST doesn’t accept visible_in_appstore, so you can’t create an entitlement hidden. To keep it out of the catalog, set visible_in_appstore to false with Update Entitlement AppStore Settings right after you create it. While the app isn’t in the AppStore, that endpoint returns 404, so hide the entitlement after you add the app to the AppStore. Entitlements that a sync imports can start hidden or visible, so check visible_in_appstore rather than assuming either. Update Entitlement changes label, description_override, and custom_approval_message_override. A field you omit keeps its value, and any other field, including the read-only description, returns 400.
  • label changes only for entitlements created in Lumos (source is manual). For any other entitlement, a different label returns 400. Its current label is accepted and changes nothing.
  • description_override is shown to requesters as description, up to 2,000 characters. Lumos stores it as sent and keeps it through syncs. null removes it, and the integration’s description returns on the next sync.
  • custom_approval_message_override takes up to 511 characters. null makes the entitlement use the app’s post_approval_message. A message for an entitlement that can’t be requested returns 422 with code set to entitlement.not_requestable. null for that entitlement is accepted and changes nothing.
Change workflows with the workflow endpoints, and change AppStore visibility with Update Entitlement AppStore Settings. Delete Entitlement fails while any account holds the entitlement. It returns 409 with code set to entitlement_in_use, and errors has one entry for active_accounts, whose message is the number of accounts that still hold it. Revoke that access first, then retry. Only entitlements from a manual source can be deleted. Any other entitlement returns 422 with code set to entitlement.not_manual. DELETE returns 409 with code set to entitlement.delete_blocked, and detail naming the reason, while any of these block the delete:
  • It has pending access requests.
  • It has time-based access scheduled for removal.
  • A draft or published Access Policy references it.

​
Finding entitlements

List Entitlements returns every entitlement in your organization, across all apps. When you already have the app or the account, start from it instead: List Entitlements and List App Entitlements take the same two filters. search is a case-insensitive substring match on label. visible_in_appstore=true returns the entitlements visible in the AppStore catalog, and visible_in_appstore=false returns the hidden ones. Either value excludes entitlements with no AppStore settings. An entitlement on an app that isn’t in the AppStore counts as hidden. AppStore settings covers which entitlements have them. All three lists return results in pages, so read Pagination before you assume that a single call returned everything.

​
Endpoints