The Task object

A task is work Lumos assigns to a user or group, such as approving an access request, creating or removing an account by hand, or handling an error. Each task links to what it’s about through app, target_user, access_request_id, and entitlement_id. Each task also has a status that changes as people act on it.

The Task object

{
  "id": "5c1d2e3f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "access-request-approval",
  "category": "approval",
  "status": "pending",
  "description": "Review Jane Doe's request for access to GitHub.",
  "instructions": null,
  "product_area": "appstore",
  "app": { "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890" },
  "target_user": {
    "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
    "email": "jane.doe@acme.com",
    "given_name": "Jane",
    "family_name": "Doe",
    "status": "active"
  },
  "resolved_by": null,
  "created_at": "2026-09-01T17:02:11.482913Z",
  "updated_at": "2026-09-01T17:02:11.482913Z",
  "access_request_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "entitlement_id": null
}

Attributes

Field	Type	Description
`id`	string	Unique identifier for the task. Always present.
`type`	string	What kind of task this is: `access-request-approval`, `manager-approval`, `account-creation`, `manual-provisioning`, `fallback-provisioning`, `account-removal`, `account-deprovisioning`, `account-modification`, `manual-deprovisioning`, `offboarding-account-removal`, `reassign-resource-owner`, `remediation`, or `error`. Always present.
`category`	string	The broader group `type` belongs to: `approval`, `manager-approval`, `provisioning`, `deprovisioning`, `ownership`, `remediation`, or `error`. Always present.
`status`	string	Where the task stands: `pending`, `accepted`, `blocked`, `staged`, `completed`, `dismissed`, `retried`, or `expired`. See Statuses. Always present.
`description`	string or null	A description of the task.
`instructions`	string or null	Instructions for completing the task.
`product_area`	string or null	The part of Lumos the task comes from: `appstore`, `access-reviews`, `onboarding`, `offboarding`, `mover`, `attribute-sync`, `platform`, or `savings`.
`app`	object or null	The app the task is about, as `{ "id": … }`.
`target_user`	object or null	The identity the task is about, as a user object.
`resolved_by`	object or null	The user who resolved the task.
`created_at`	string	When Lumos created the task. Always present.
`updated_at`	string	When the task last changed. Always present.
`access_request_id`	string or null	The access request the task belongs to, if any.
`entitlement_id`	string or null	The entitlement the task grants or removes. See Entitlement IDs on tasks.
`assignees`	array	The users and groups the task is assigned to. Only present with `expand=assignees`. A user assigned through a custom attribute, such as a manager field, is listed as the user the attribute names now.
`actions`	array	What you can do to the task, and the statuses each action leads to. Only present with `expand=actions`.
`comments`	array	Comments on the task. Only present with `expand=comments`, which only Get Task accepts.

Every field above except assignees, actions, and comments is always present, with null when it has no value.

Statuses

Status	Meaning
`pending`	Created and waiting for someone to act on it.
`accepted`	Someone is working on it.
`blocked`	It can’t be resolved as assigned, for example because the group it’s assigned to has no members.
`staged`	Lumos doesn’t currently put tasks in this status.
`completed`	Someone did what it asked.
`dismissed`	Closed without doing it.
`retried`	An error task whose failed step was retried.
`expired`	It expired before anyone acted on it.

pending, accepted, and blocked are the open statuses. completed, dismissed, retried, and expired are final.

Which tasks you can see

What you can do with a task depends on how it’s assigned to you and on your role. A token acts as its user, so the same rules apply to API tokens. The table covers List Tasks, Get Task, List Task Actions, and the endpoints that act on a task.

You are	List Tasks shows	Get Task and List Task Actions	Acting on the task
Assigned directly or through a group	The task	Works	Works
Assigned through a custom attribute, such as a manager field	The task	Works	Works
An App Admin who isn’t assigned	Tasks on the apps they administer	`403`	Not allowed
An Admin	Every task, with `show_all_tasks=true`	Works	Works, including on approval tasks they aren’t assigned to, through `override-approve-access-request` and `override-deny-access-request`
A Read Only Admin or AppStore Read Only Admin	Every task, with `show_all_tasks=true`	Works	Only on tasks they’re assigned to
A custom role that can view every task	Every task, with `show_all_tasks=true`	Works	Only on tasks they’re assigned to

show_all_tasks=true returns 403 for anyone the table doesn’t list with it. Acting on a task you aren’t assigned to requires the built-in Admin role.

Filtering the list

Parameter	Effect
`status`	One status. Without it, the list returns only open tasks: `pending`, `accepted`, and `blocked`.
`type`	One task type.
`category`	One category. Ignored when `type` is set.
`product_area`	One product area.
`search`	A search string.
`assigned_user_ids`	Tasks assigned to these users, directly, through a group, or through a custom attribute. An unknown ID returns `404`.
`assigned_group_ids`	Tasks assigned to these groups. An unknown ID returns `404`.
`access_request_id`	Tasks on one access request. An unknown ID returns `404`.
`show_all_tasks`	Every task in your organization, for the roles above.
`order_by`	`created_at`, `type`, `app`, or `target_user`, optionally followed by `desc`. Newest first by default.

An unknown value for status, type, category, or product_area returns 400. An order_by value outside the list above also returns 400. One unknown ID in assigned_user_ids or assigned_group_ids returns 404 with code not_found, even when the other IDs match. The maximum page_size on this endpoint is 100. List Tasks reduces a larger value to 100.

Acting on a task

Four endpoints act on a task, and a fifth adds a comment. The four return 204 when they succeed. Complete or dismiss. Complete Task and Dismiss Task run the one action that moves the task to completed or dismissed. When there isn’t exactly one such action:

If no action moves the task to that status, the call returns 400 with code task.no_action_for_status.
If such an action exists but you can’t take it, the call returns 403.
If you can take more than one, the call returns 400 with code task.action_ambiguous. Use Perform Task Action to choose one.
If the task is already completed or dismissed, the call returns 400 with code task.no_action_for_status, because no action moves a finished task.

Perform a specific action. Call List Task Actions first, or list tasks with expand=actions. Each item has an action_type and the transitions it can make. An assignee of a pending task of type access-request-approval sees something like this:

[
  { "action_type": "reassign-access-request", "transitions": [{ "transition_to": null }] },
  { "action_type": "approve-access-request", "transitions": [{ "transition_to": "completed" }] },
  { "action_type": "deny-access-request", "transitions": [{ "transition_to": "dismissed" }] }
]

A transition_to of null means the action leaves the status as it is. Send the action_type to Perform Task Action. Add transition_to to choose the resulting status. It must be one of that action’s transitions. Otherwise the call returns 400 with code task.transition_not_allowed. When the action has one transition, omit transition_to, and Lumos uses that transition. An action_type that Lumos doesn’t recognize returns 400 with code task.action_unknown. Reassign. Reassign Task replaces the task’s assignees with the user_ids and group_ids you send. Send "replace": false to add them to the existing assignees instead.

Reassign Task skips IDs that don’t match a user or group. If none match, the call returns 400.
Replacing also removes assignments made through a custom attribute, such as a manager field. assignees lists such an assignment as a user, so sending that list back assigns that user directly, and the task stops following the attribute.
For some task types, reassigning also changes the status. A blocked task of type account-removal returns to pending.

Comment. Create Task Comment adds a comment of 1 to 4,000 characters and returns it with 201. The four endpoints that act on a task return 409 with code task.already_in_status when the task is already in the status the action would move it to. Any of the five endpoints returns 403 when you aren’t allowed to take the action.

Entitlement IDs on tasks

entitlement_id is the id of the entitlement the task grants or removes. Pass it to Get Entitlement. It’s null when the task isn’t about one entitlement. Approval tasks always carry null. If you’re moving from requestable permissions, see Migrate requestable permissions to entitlements.

Endpoints

Endpoint	Path
List Tasks	`GET /v1/tasks`
Get Task	`GET /v1/tasks/{task_id}`
List Task Actions	`GET /v1/tasks/{task_id}/actions`
Complete Task	`POST /v1/tasks/{task_id}:complete`
Dismiss Task	`POST /v1/tasks/{task_id}:dismiss`
Perform Task Action	`POST /v1/tasks/{task_id}:perform-action`
Reassign Task	`POST /v1/tasks/{task_id}:reassign`
Create Task Comment	`POST /v1/tasks/{task_id}/comments`

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

The Task object

Attributes

Statuses

Which tasks you can see

Filtering the list

Acting on a task

Entitlement IDs on tasks

Endpoints

​Attributes

​Statuses

​Which tasks you can see

​Filtering the list

​Acting on a task

​Entitlement IDs on tasks

​Endpoints

Attributes

Statuses

Which tasks you can see

Filtering the list

Acting on a task

Entitlement IDs on tasks

Endpoints