Update Entitlement

curl --request PATCH \
  --url https://api.lumos.com/v1/entitlements/{entitlement_uuid} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "Viewer"
}
'

import requests

url = "https://api.lumos.com/v1/entitlements/{entitlement_uuid}"

payload = { "label": "Viewer" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({label: 'Viewer'})
};

fetch('https://api.lumos.com/v1/entitlements/{entitlement_uuid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lumos.com/v1/entitlements/{entitlement_uuid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'label' => 'Viewer'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lumos.com/v1/entitlements/{entitlement_uuid}"

	payload := strings.NewReader("{\n  \"label\": \"Viewer\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.lumos.com/v1/entitlements/{entitlement_uuid}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"Viewer\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/entitlements/{entitlement_uuid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"label\": \"Viewer\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "app_id": "<string>",
  "label": "<string>",
  "entitlement_type_label": "<string>",
  "source": "google-workspace-quick-inbox",
  "description": "<string>",
  "description_override": "<string>",
  "approval_workflow_override": {
    "id": "<string>",
    "type": "approval",
    "steps": [
      {
        "step": "<string>",
        "inputs": {},
        "name": "<string>"
      }
    ],
    "name": "<string>",
    "description": "<string>",
    "app_id": "<string>"
  },
  "provisioning_workflow": {
    "id": "<string>",
    "type": "approval",
    "steps": [
      {
        "step": "<string>",
        "inputs": {},
        "name": "<string>"
      }
    ],
    "name": "<string>",
    "description": "<string>",
    "app_id": "<string>"
  },
  "deprovisioning_workflow": {
    "id": "<string>",
    "type": "approval",
    "steps": [
      {
        "step": "<string>",
        "inputs": {},
        "name": "<string>"
      }
    ],
    "name": "<string>",
    "description": "<string>",
    "app_id": "<string>"
  },
  "custom_approval_message_override": "<string>",
  "appstore_settings": {
    "visible_in_appstore": true,
    "allowed_requester_group_uuids_override": [
      "<string>"
    ],
    "time_based_access_override": {
      "options": [
        {
          "label": "<string>",
          "value_seconds": 123
        }
      ]
    },
    "request_validation_webhook_uuid": "<string>"
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Entitlements

Update Entitlement

Update an entitlement’s label, description_override and custom_approval_message_override. Fields you omit are left unchanged. Any other field, including the read-only description, returns 400.

Only entitlements created in Lumos (source is manual) can be renamed; sending a new label for a synced one returns 400 and changes nothing, while its current label is accepted and ignored. A description_override is stored as sent and kept across syncs, on synced entitlements too; null removes it, and is accepted and ignored when none is set. A non-null custom_approval_message_override on an entitlement that can’t be requested returns 422 with code entitlement.not_requestable, while null is accepted and ignored.

Returns 404 if the entitlement is unknown in the caller’s organization.

PATCH

entitlements

{entitlement_uuid}

Update Entitlement

curl --request PATCH \
  --url https://api.lumos.com/v1/entitlements/{entitlement_uuid} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "Viewer"
}
'

import requests

url = "https://api.lumos.com/v1/entitlements/{entitlement_uuid}"

payload = { "label": "Viewer" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({label: 'Viewer'})
};

fetch('https://api.lumos.com/v1/entitlements/{entitlement_uuid}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lumos.com/v1/entitlements/{entitlement_uuid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'label' => 'Viewer'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lumos.com/v1/entitlements/{entitlement_uuid}"

	payload := strings.NewReader("{\n  \"label\": \"Viewer\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.lumos.com/v1/entitlements/{entitlement_uuid}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"Viewer\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/entitlements/{entitlement_uuid}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"label\": \"Viewer\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "app_id": "<string>",
  "label": "<string>",
  "entitlement_type_label": "<string>",
  "source": "google-workspace-quick-inbox",
  "description": "<string>",
  "description_override": "<string>",
  "approval_workflow_override": {
    "id": "<string>",
    "type": "approval",
    "steps": [
      {
        "step": "<string>",
        "inputs": {},
        "name": "<string>"
      }
    ],
    "name": "<string>",
    "description": "<string>",
    "app_id": "<string>"
  },
  "provisioning_workflow": {
    "id": "<string>",
    "type": "approval",
    "steps": [
      {
        "step": "<string>",
        "inputs": {},
        "name": "<string>"
      }
    ],
    "name": "<string>",
    "description": "<string>",
    "app_id": "<string>"
  },
  "deprovisioning_workflow": {
    "id": "<string>",
    "type": "approval",
    "steps": [
      {
        "step": "<string>",
        "inputs": {},
        "name": "<string>"
      }
    ],
    "name": "<string>",
    "description": "<string>",
    "app_id": "<string>"
  },
  "custom_approval_message_override": "<string>",
  "appstore_settings": {
    "visible_in_appstore": true,
    "allowed_requester_group_uuids_override": [
      "<string>"
    ],
    "time_based_access_override": {
      "options": [
        {
          "label": "<string>",
          "value_seconds": 123
        }
      ]
    },
    "request_validation_webhook_uuid": "<string>"
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

entitlement_uuid

string

required

The entitlement's ID, which GET /v1/entitlements and GET /v1/apps/{app_uuid}/entitlements return as id.

Body

application/json

Request body for PATCH /v1/entitlements/{entitlement_uuid}.

label

string

New human-readable label for the entitlement. Only entitlements created in Lumos (source is manual) can be renamed; the integration owns a synced entitlement's label.

description_override

string | null

Description shown to requesters in place of the integration's, kept as sent and across syncs. null removes it, and the integration's own description returns on its next sync; when none is set, null changes nothing.

Required string length: 1 - 2000

custom_approval_message_override

string | null

Message sent when a request is approved. null inherits the app's message.

Required string length: 1 - 511

Response

Successful Response

Public-API representation of an Entitlement.

string

required

The ID of this entitlement.

app_id

string

required

The ID of the app that owns this entitlement.

label

string

required

Human-readable label for the entitlement (e.g. a role or license name).

entitlement_type_label

string

required

Human-readable label for the entitlement's type (e.g. 'Role', 'License', 'Group').

source

enum<string>

required

How this entitlement was discovered. manual is created in Lumos; other values come from an upstream integration.

Available options:

google-workspace-quick-inbox,

google-workspace-deep-inbox,

microsoft-deep-inbox,

microsoft-oauth,

microsoft-gcc,

google-workspace-oauth,

okta,

manual,

onelogin,

atlassian,

google-cloud,

integration,

jumpcloud,

custom,

mcp,

native

description

string | null

The description shown to requesters: description_override if set, otherwise the integration's own description. Read-only; set description_override instead.

description_override

string | null

The description set in Lumos, kept across syncs. Null when none is set, and the entitlement shows its integration's description.

approval_workflow_override

Workflow · object

Response shape for a Workflow.

Workflow
WorkflowRef

Show child attributes

provisioning_workflow

Workflow · object

Response shape for a Workflow.

Workflow
WorkflowRef

Show child attributes

deprovisioning_workflow

Workflow · object

Response shape for a Workflow.

Workflow
WorkflowRef

Show child attributes

custom_approval_message_override

string | null

This entitlement's own custom approval message, shown to requesters when the entitlement is approved, overriding the app's. Null means this entitlement inherits the app's approval message.

appstore_settings

EntitlementAppStoreSettings · object | null

The entitlement's AppStore-catalog settings. Null unless expanded with expand=appstore_settings. Omitted entirely (not present, not null) when the parent app isn't enrolled in the AppStore.

Show child attributes

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

Update Entitlement

Authorizations

Path Parameters

Body

Response