The Access Policy object

An Access Policy grants apps, and optionally specific entitlements on them, to every identity that matches its condition. Each app on a policy can also be pre-approved, so requests the policy creates for the app and its listed entitlements skip approval.

{
  "id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
  "name": "Engineering baseline",
  "business_justification": "Every engineer needs source control from day one.",
  "status": "published",
  "is_enabled": true,
  "apps": [
    {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "label": "GitHub",
      "is_preapproved": true,
      "entitlements": [
        { "id": "4d5e6f70-8192-4a3b-8c4d-5e6f70819203", "label": "Member" }
      ]
    }
  ],
  "access_condition": {
    "attribute": { "label": "Department", "value": "identity.custom_attributes['Department']" },
    "equals": { "label": "Engineering", "value": "Engineering" }
  },
  "is_everyone_condition": false
}

Attributes

Field	Type	Description
`id`	string	Unique identifier for the policy. Always present.
`name`	string	The policy’s name. Always present.
`business_justification`	string	Why the policy exists. Always present.
`status`	string	`draft` or `published`. See Drafts, publishing, and enabling. Always present.
`is_enabled`	boolean	Whether the policy is enabled. Always present.
`apps`	array	The apps the policy grants, each with its entitlements. See Grants. Always present.
`access_condition`	object	The condition an identity must match. See Conditions. Always present.
`is_everyone_condition`	boolean	Whether the policy applies to everyone. Always present.
`owners`	object	The users and groups that own the policy. Only present with an owners `expand`. See Owners.

Each item in apps:

Field	Type	Description
`id`	string	The app’s ID.
`label`	string	The app’s display name. Returned on reads only.
`is_preapproved`	boolean	Whether requests the policy creates for this app, and for each entitlement in `entitlements`, are pre-approved.
`entitlements`	array	The entitlements granted on the app, each `{id, label}`. An entitlement’s `label` is returned on reads only.

A write body that includes label on an app or entitlement returns 400.

Grants

Each grant is an entitlement ID in apps[].entitlements[].id. It’s the same ID that Get Entitlement takes. To grant access to the app itself rather than to specific entitlements, omit entitlements or send an empty list. Migrate Access Policies covers moving existing grants to entitlement IDs. A policy needs at least one app, and an empty apps list returns 400. When you create or update a policy, Lumos checks every ID in apps:

Problem	Response
An app or entitlement ID that doesn’t match one in your organization	`404`
An entitlement that can’t be requested	`404`
An entitlement listed under an app it doesn’t belong to	`400` with “One or more selected permissions are not available for the selected app.”

The 400 message calls grants “permissions”.

Drafts, publishing, and enabling

A policy grants access only while it’s both published and enabled.

Create returns 201 with the new policy. It makes a draft unless you send "status": "published", and it leaves the policy disabled unless you send "is_enabled": true. A draft can’t be enabled, so on create, "is_enabled": true returns 400 unless you also send "status": "published".
Publish a draft by sending "status": "published" on Update Access Policy. You can’t return a published policy to draft. Sending "status": "draft" for a published policy returns 400.
Approval. When your organization requires approval before publishing, creating a policy with "status": "published" returns 400, and so does publishing a draft whose changes aren’t approved. Create a draft and submit it for approval in the Lumos UI.
Update a published policy with PUT, which replaces every field, or with PATCH, where a field you omit keeps its value and no field can be null. The update takes effect immediately. If the policy also has a draft version saved in Lumos, either call returns 400 with “Access policy already has a draft version.”
Read returns the published version when there is one, and the draft version otherwise.
Delete removes the policy and the pre-approval it gave its apps, and returns 204.

status takes only draft or published, so an uppercase value such as PUBLISHED returns 400. Updating or deleting a policy doesn’t remove access that identities already received through it. When an identity stops matching a policy, Lumos removes the access that the policy granted only if your organization has enabled Auto Run in its Movers settings. Even then, Lumos keeps access that the identity requested through the AppStore.

Conditions

Send access_condition with the condition that identities must match, or send "is_everyone_condition": true to apply the policy to everyone. Sending both returns 400 on every write. The exception is the everyone condition that a read returns: Lumos reads it as "is_everyone_condition": true, so you can send a read’s access_condition back as is. Lumos checks the condition when you save it. What Lumos rejects lists what returns 400. Reads set is_everyone_condition to true only for this exact condition, label included. Any other condition that matches every identity reads back as is_everyone_condition: false. Conditions documents the format, and the stored form that a read returns. Two published policies can’t have the same condition. If creating, publishing, or updating a policy would give a published policy the same condition as another published policy, the call returns 400 with “An access policy with these conditions already exists.” Drafts can share a condition.

Who can do what

The built-in roles can do the following:

Role	Can
Admin	Every action: create, read, update, publish, enable, and delete.
Read Only Admin	Read every policy.
A policy’s owners	Read the policy, and update the apps on it while it’s a draft.
A policy’s commenters	Read the policy.

A custom role can also allow these actions. On a PUT or PATCH, Lumos checks permission for each changed field on its own, so an owner can update a draft’s apps, but gets 403 for a change to its name, justification, or condition. A call you aren’t allowed to make returns 403.

Owners

List Access Policies and Get Access Policy add each policy’s owners when you send one of these expand values:

`expand`	What `owners` holds
`owners`	A `users` list and a `groups` list, with each owner as `{id}`.
`owners.users`	The same, except each user is a full user.
`owners.groups`	The same, except each group is a full group.

With expand=owners.users, a policy’s owners look like this:

"owners": {
  "users": [
    {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "email": "ada@acme.com",
      "given_name": "Ada",
      "family_name": "Lovelace",
      "status": "active"
    }
  ],
  "groups": [{ "id": "2b3c4d5e-6f70-8901-bcde-f12345678901" }]
}

The group is {id} because only owners.users was sent. To get full users and full groups, send both, such as expand=owners.users,owners.groups. Without an owners expand, the response has no owners. A user that List Users treats as deleted isn’t listed. Any owners expand needs permission to call both List Users and List Groups. Without both, the call returns 403.

Lumos enables owners per organization. Until it’s enabled for yours, an owners expand returns 400. To enable it, contact your Lumos representative.

Listing

List Access Policies returns the policies you can read, newest first. name limits the list to policies whose name contains that text, ignoring case. A page can be empty while later pages still hold policies, as Short and empty pages describes.

Endpoints

Endpoint	Path
List Access Policies	`GET /v1/access-policies`
Create Access Policy	`POST /v1/access-policies`
Get Access Policy	`GET /v1/access-policies/{access_policy_id}`
Update Access Policy	`PUT /v1/access-policies/{access_policy_id}`
Patch Access Policy	`PATCH /v1/access-policies/{access_policy_id}`
Delete Access Policy	`DELETE /v1/access-policies/{access_policy_id}`

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

The Access Policy object

Attributes

Grants

Drafts, publishing, and enabling

Conditions

Who can do what

Owners

Listing

Endpoints

​Attributes

​Grants

​Drafts, publishing, and enabling

​Conditions

​Who can do what

​Owners

​Listing

​Endpoints

Attributes

Grants

Drafts, publishing, and enabling

Conditions

Who can do what

Owners

Listing

Endpoints