The Access Request object

An access request is someone asking for access to an app, and optionally to specific entitlements on it. The user who asks is the requester, and the identity the access is for is the target. They can be the same user. Filing a request starts its approval workflow. The request’s status tracks the workflow through approval and provisioning. For time-based access, it also tracks removal. Approvals and manual provisioning steps appear as tasks on the request.

{
  "id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "app_name": "GitHub",
  "requester_user": {
    "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
    "email": "jane.doe@acme.com",
    "given_name": "Jane",
    "family_name": "Doe",
    "status": "active"
  },
  "target_user": {
    "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
    "email": "jane.doe@acme.com",
    "given_name": "Jane",
    "family_name": "Doe",
    "status": "active"
  },
  "supporter_user": null,
  "status": "pending-approval",
  "notes": {},
  "expires_at": null,
  "expiration_in_seconds": null,
  "requested_at": "2026-09-01T17:02:10.905133Z",
  "entitlements": [
    { "id": "4d5e6f70-8192-4a3b-8c4d-5e6f70819203", "label": "Maintainer" }
  ]
}

Attributes

Field	Type	Description
`id`	string	Unique identifier for the request. Always present.
`app_id`	string	The app the request is for. Always present.
`app_name`	string	The app’s display name. Always present.
`requester_user`	object or null	The user who asked. `null` for requests Lumos filed itself, such as those from an Access Policy.
`target_user`	object	The identity the access is for, as a user object. Always present.
`supporter_user`	object or null	The last approver, other than a manager, who approved or denied the request. `null` until such an approver acts.
`status`	string	Where the request stands. See Statuses. Always present.
`notes`	object	Notes people left when they acted on the request, keyed by the status they moved it to.
`expires_at`	string or null	For time-based access, when the granted access ends. `null` for permanent access.
`expiration_in_seconds`	integer or null	For time-based access, how long after provisioning the access lasts. `null` for permanent access.
`requested_at`	string or null	When the requester filed the request.
`entitlements`	array	The entitlements requested, each `{id, label}`. See Entitlements on a request.
`tasks`	array	The request’s tasks that you can see. Only present with `expand=tasks`.
`custom_fields`	array	The requester’s answers to the app’s custom intake fields, each `{reference_key, prompt, response}`. `reference_key` is `null` when the field was deleted after the request was filed. Only present with `expand=custom_fields`.

Who can see a request

You can see requests you filed and requests where you’re the target. Of the built-in roles, Admin, Read Only Admin, AppStore Read Only Admin, and App Admin can see every request in your organization. A custom role can also grant this access. Get Access Request, List Access Requests, and Cancel Access Request act only on requests you can see. List Access Requests applies this whatever filters you pass. The approver of a request’s current stage can also get the request with Get Access Request, until the request no longer waits on them. List Access Requests doesn’t return it for them.

Statuses

status is one of the values below. The statuses marked cancellable are the ones a request holds while it’s still in progress. Cancelling returns 409 for the others.

Status	Meaning	Cancellable
`pending`	Just filed. Nothing has been decided yet.	Yes
`pending-manager-approval`	Waiting for a manager to approve it.	Yes
`manager-approved`	A manager approved it. It can still need another approval.	Yes
`manager-denied`	A manager denied it.	No
`pending-approval`	Waiting for an approver.	Yes
`approved`	An approver approved it, or it needed no approval. Provisioning comes next.	Yes
`denied`	Denied during approval.	No
`expired`	Nobody approved or denied it in time.	No
`cancelled`	Cancelled before it finished.	No
`pending-provisioning`	Being provisioned. A request can also stay in this status while a manual provisioning task is open. Check its tasks rather than waiting for the next status.	Yes
`pending-manual-provisioning`	Waiting for someone to grant the access by hand.	Yes
`denied-provisioning`	Someone declined to grant the access at provisioning time.	No
`provisioned`	The access is in place, and Lumos is finishing the request.	Yes
`completed`	Finished, with nothing more pending.	No
`pending-deprovisioning`	Time-based access ended, and Lumos is removing it.	Yes
`pending-manual-deprovisioning`	Time-based access ended, and someone has to remove it by hand.	Yes
`time-based-expired`	Time-based access ended, and the access was removed.	No
`time-based-expired-failed`	Removing the time-based access failed, and the removal is unresolved.	No
`time-based-expired-cancelled`	The removal was cancelled before it removed the access, for example because a newer request renewed the access.	No
`reverting`	Someone chose to undo the request, and the undo hasn’t finished.	Yes
`reverted`	The undo finished.	No

Filing a request

Create Access Request needs an app_id and a business_justification:

{
  "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "entitlement_ids": ["4d5e6f70-8192-4a3b-8c4d-5e6f70819203"],
  "business_justification": "Maintaining the release pipeline this quarter.",
  "access_length": "30 days"
}

The justification is required. A call without business_justification returns 400. Create Access Request still accepts the deprecated note field in its place.
The target is you unless you send target_user_id.
The requester is you. Only an Admin can send requester_user_id to file on someone else’s behalf. If anyone else sends it, the call returns 403.
access_length must be one of the time-based access options the app offers. When you name entitlements, it must be an option that all of them offer. Any other value returns 400. Omit it for permanent access, which works only if the app offers Unlimited. The possible options are: 2 hours, 4 hours, 8 hours, 12 hours, 1 day, 2 days, 3 days, 7 days, 14 days, 30 days, 90 days, and Unlimited.
custom_fields answers the app’s custom intake fields, keyed by reference_key, such as {"environment": "Production"}. Every required field needs an answer that isn’t blank. An answer can be up to 500 characters, and a dropdown answer must match one of its options exactly. A missing answer, an unknown key, or an answer that breaks these rules returns 400 with code set to access_request.custom_fields_invalid. errors lists each problem, with field set to custom_fields.<reference_key>.

A successful call returns 201 with an access_requests list. One call can create more than one request, so read the list rather than assuming a single item. An app_id, target_user_id, or requester_user_id that doesn’t exist in your organization returns 404. If the requester isn’t allowed to file the request, the call returns 403 with code set to access_request.forbidden. Lumos can refuse a request for other reasons, such as a webhook that rejects it. These return 400 with code set to access_request. followed by the reason: invalid, not_requestable, entitlement_invalid, access_length_invalid, expiration_invalid, itsm_ticket_id_required, missing_fields, or rejected_by_webhook.

Entitlements on a request

entitlement_ids takes entitlement IDs, the IDs that List Entitlements returns. To see what an app offers a requester, call Get App Entitlement AppStore Catalog. Omit entitlement_ids to request the app itself. Each entitlement must be one you can request on the app in app_id. Otherwise the call fails:

Response	When
`404` with `code` `access_request.entitlement_not_found`	No entitlement with that ID exists in your organization.
`400` with `code` `access_request.entitlement_not_requestable`	The entitlement exists, but you can’t request it on this app.

Get Access Request and List Access Requests return entitlements as {id, label} objects. Each entitlement appears once. If you’re moving from requestable permissions, see Migrate requestable permissions to entitlements.

Time-based access

Send access_length to request access that ends. Lumos turns it into seconds when you file, and two fields track it:

expiration_in_seconds is the length, for example 2592000 for 30 days.
expires_at is null until the access is granted. After that, it’s the time the access ends, which is the time of the grant plus expiration_in_seconds.

When that time comes, Lumos runs the app’s deprovisioning workflow, which removes the access or creates a manual deprovisioning task. The request moves through pending-deprovisioning or pending-manual-deprovisioning to time-based-expired. An access_length of Unlimited, or none at all, means permanent access, and both fields stay null.

Cancelling

Cancel Access Request takes an optional reason and returns 204:

{ "reason": "No longer needed." }

You can cancel a request while Statuses marks its status as cancellable. In any other status, the call returns 409. The requester, the target, and an Admin can cancel a request. Anyone else who can see the request, such as an App Admin or the approver of its current stage, gets 403.

Expanding a request

expand=tasks adds the request’s tasks that you can see. Each task has the same shape that Get Task returns when you send no expand.
expand=custom_fields adds the requester’s answers to the app’s custom intake fields.

Listing

Parameter	Effect
`user_id`	Requests where this user is the requester or the target.
`requester_user_id`	Requests this user filed.
`target_user_id`	Requests where this user is the target.
`statuses`	Requests in any of these statuses. Repeat the parameter for more than one.
`order_by`	`created_at` (the default, oldest first) or `created_at desc` (newest first), by when the request was filed.

statuses takes the labels in Statuses. Any other value, such as PENDING_APPROVAL, returns 400. A user ID that doesn’t exist in your organization returns 404. A page token works only with the same filters and order_by as the call that returned it. Pagination covers page tokens.

Endpoints

Endpoint	Path
List Access Requests	`GET /v1/access-requests`
Create Access Request	`POST /v1/access-requests`
Get Access Request	`GET /v1/access-requests/{id}`
Cancel Access Request	`POST /v1/access-requests/{id}:cancel`

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

The Access Request object

Attributes

Who can see a request

Statuses

Filing a request

Entitlements on a request

Time-based access

Cancelling

Expanding a request

Listing

Endpoints

​Attributes

​Who can see a request

​Statuses

​Filing a request

​Entitlements on a request

​Time-based access

​Cancelling

​Expanding a request

​Listing

​Endpoints

Attributes

Who can see a request

Statuses

Filing a request

Entitlements on a request

Time-based access

Cancelling

Expanding a request

Listing

Endpoints