Create Entitlement

curl --request POST \
  --url https://api.lumos.com/v1/entitlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "label": "Editor"
}
'

import requests

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

payload = {
    "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "label": "Editor"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({app_id: '1a2b3c4d-5e6f-7890-abcd-ef1234567890', label: 'Editor'})
};

fetch('https://api.lumos.com/v1/entitlements', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app_id' => '1a2b3c4d-5e6f-7890-abcd-ef1234567890',
    'label' => 'Editor'
  ]),
  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"

	payload := strings.NewReader("{\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"label\": \"Editor\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.lumos.com/v1/entitlements")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"label\": \"Editor\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"label\": \"Editor\"\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>"
      }
    ]
  }
}

POST

entitlements

Create Entitlement

curl --request POST \
  --url https://api.lumos.com/v1/entitlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "label": "Editor"
}
'

import requests

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

payload = {
    "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "label": "Editor"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({app_id: '1a2b3c4d-5e6f-7890-abcd-ef1234567890', label: 'Editor'})
};

fetch('https://api.lumos.com/v1/entitlements', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app_id' => '1a2b3c4d-5e6f-7890-abcd-ef1234567890',
    'label' => 'Editor'
  ]),
  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"

	payload := strings.NewReader("{\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"label\": \"Editor\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.lumos.com/v1/entitlements")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"label\": \"Editor\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"label\": \"Editor\"\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>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Request body for POST /v1/entitlements.

app_id

string

required

The ID of the app that will own this entitlement.

label

string

required

Human-readable label for the entitlement.

description_override

string | null

Description shown to requesters, kept as sent. Omit it, or send null, for no description.

Required string length: 1 - 2000

custom_approval_message_override

string | null

Message sent when a request is approved. Omit it, or send null, to inherit 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

Create Entitlement

Authorizations

Body

Response