Skip to main content
A v0 requestable permission was two things in one object: the grantable access itself, and its AppStore settings in request_config (visibility, allowed groups, approvals, provisioning, and webhooks). v1 splits them. The entitlement is the grantable access. What v0 kept in request_config is now the entitlement’s AppStore settings, at /v1/entitlements/{entitlement_uuid}/appstore-settings, and its three bound workflows, so one v0 write often becomes several v1 calls.

​
Identifiers

v0 requestable-permission IDs and v1 entitlement IDs are different values. Each v0 requestable permission corresponds to exactly one v1 entitlement, but its v0 id won’t work in a v1 path. GET /v1/entitlements/{entitlement_uuid} returns 404 for it. The same applies everywhere v1 refers to an entitlement. Access Policies list entitlements by entitlement ID, access requests take entitlement_ids, and tasks carry an entitlement_id. No v1 response carries a requestable-permission ID.

​
Endpoints

The list filters changed too:
  • search_term is now search, a case-insensitive substring match on label. There’s no exact_match.
  • in_app_store is now visible_in_appstore.
  • include_inherited_configs is gone. Where the entitlement inherits a setting from its app, v1 returns that override as null, not the app’s value.
  • List Entitlements has no app_id filter. Use List App Entitlements for one app.
The object changed shape. app_class_id, app_instance_id, type, and request_config are gone. v1 adds entitlement_type_label, source, description, description_override, the three workflow fields, custom_approval_message_override, and appstore_settings, which you get with expand=appstore_settings. source tells you where the entitlement came from. manual means someone created it in Lumos.

​
Where each request_config field went

​
Creating an entitlement

v0 created a requestable permission and its whole request_config in one call. v1 takes several:
  1. Call Create Entitlement with app_id, label, and optionally description_override and custom_approval_message_override.
  2. Call Update Entitlement AppStore Settings to set visibility, allowed groups, time-based access, and the validation webhook.
  3. Call the workflow endpoints to set the approval, provisioning, and deprovisioning workflows.
v1 makes a new entitlement visible in the AppStore as soon as it exists, so code ported from v0 makes new entitlements requestable immediately. v0 created a requestable permission hidden unless the body set appstore_visibility to VISIBLE. To keep one hidden, set visible_in_appstore to false with Update Entitlement AppStore Settings right after you create it.
An entitlement’s AppStore settings exist only while its app is in the AppStore. Until then, reading or updating them returns 404, and nobody can request the entitlement. v0 returned request_config either way. Use this order:
  1. Add the app to the AppStore while its catalog_visibility is still hidden. A new app starts as hidden.
  2. Set each entitlement’s visible_in_appstore.
  3. Make the app visible.
Set up an app in the AppStore describes each step.
v0
v1

​
Provisioning groups and webhooks

v1 expresses these three v0 settings as steps in the entitlement’s workflows: Inline webhook IDs come from List Inline Webhooks. Create the workflow with Create Workflow. Then bind it to the entitlement with Set Entitlement Provisioning Workflow or Set Entitlement Deprovisioning Workflow.

​
What v1 doesn’t do yet

These v0 writes have no v1 equivalent yet. Until v1 supports them, make these changes in the Lumos UI.
  • Renaming a synced entitlement. Update Entitlement changes the label only for entitlements created in Lumos (source is manual). For any other entitlement, a new label returns 400. v0 renamed any requestable permission.
  • Configuring an entitlement while its app isn’t in the AppStore. Add the app first, as Creating an entitlement describes.

​
Terraform

In version 1.x of the Lumos Terraform provider, lumos_requestable_permission becomes lumos_entitlement and lumos_entitlement_appstore_settings, and its approval and provisioning overrides move into workflows. You import each one by its entitlement’s ID, which isn’t the permission’s ID. Migrating from 0.x to 1.x covers finding those IDs and maps each attribute.