Access requests and tasks

An access request moves through approval, provisioning and, for time-based access, removal. Where a step needs a person, Lumos creates a task and assigns it. This guide follows a request through those steps and builds a bot that approves requests from code. The Access Request object and the Task object list every field.

How a request moves

Filing a request starts its approval workflow. From there:

Approval. Each approval stage creates an access-request-approval task for the stage’s approvers. A request that needs no approval moves directly to approved.
Provisioning. When Lumos can grant the access itself, for example through the app’s integration, provisioning runs automatically. Otherwise Lumos creates a task, such as manual-provisioning or account-creation, for someone to grant it by hand. The app’s admins get that task unless the workflow names someone else.
Removal. When time-based access ends, Lumos removes it automatically or creates a deprovisioning task, such as manual-deprovisioning or account-deprovisioning, for someone to remove it by hand.

Statuses describes every status, and which ones you can cancel from.

File a request and follow it

The code on this page uses Python 3 and the requests library. It reads your API token from the LUMOS_API_TOKEN environment variable, as Authentication describes, and stops on any error, including a 429. Rate limits explains how to wait and retry instead. Create Access Request takes the app, the entitlements you want on it, and a business justification:

File a request

import os
import time

import requests

BASE_URL = "https://api.lumos.com"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['LUMOS_API_TOKEN']}"

response = session.post(
    f"{BASE_URL}/v1/access-requests",
    json={
        "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",
    },
)
response.raise_for_status()
# One submission can create more than one request, so read the whole list.
request_ids = [request["id"] for request in response.json()["access_requests"]]

entitlement_ids takes entitlement IDs, as List Entitlements returns them. Omit it to request the app itself. Filing a request covers the other fields and the errors each can return, and Time-based access covers access_length. The API doesn’t send an event when a request changes status or when Lumos creates a task. To follow a request, poll it. Each poll counts against your rate limit, so increase the wait after each poll:

Follow a request

IN_PROGRESS = {
    "pending",
    "pending-manager-approval",
    "manager-approved",
    "pending-approval",
    "approved",
    "pending-provisioning",
    "pending-manual-provisioning",
    "provisioned",
    "pending-deprovisioning",
    "pending-manual-deprovisioning",
    "reverting",
}


def follow(request_id, max_delay=300, max_wait=24 * 60 * 60):
    """Poll a request until it leaves the in-progress statuses, doubling the wait each time.

    Raises TimeoutError if the request is still in progress after max_wait seconds.
    """
    deadline = time.monotonic() + max_wait
    delay = 10
    while True:
        response = session.get(f"{BASE_URL}/v1/access-requests/{request_id}")
        response.raise_for_status()
        request = response.json()
        if request["status"] not in IN_PROGRESS:
            return request
        if time.monotonic() + delay > deadline:
            raise TimeoutError(f"Request {request_id} is still {request['status']}")
        time.sleep(delay)
        delay = min(delay * 2, max_delay)


for request_id in request_ids:
    request = follow(request_id)
    print(request["id"], request["status"])

follow() returns when the request reaches a status that isn’t cancellable, such as completed, denied, expired, or cancelled. A request for time-based access moves back to an in-progress status when its access ends. A request can wait on a person for days, so follow() raises TimeoutError if the request is still in progress after max_wait seconds.

The tasks on a request

Two calls return a request’s tasks:

Get Access Request with expand=tasks returns them in any status.
List Tasks with access_request_id returns the open ones, unless you pass status.

Both return only the tasks you can see, as Which tasks you can see describes. A requester who follows their own request usually sees no tasks at all, because approval tasks go to the approvers. A provisioning or deprovisioning task for one requested entitlement carries that entitlement’s ID, as Entitlement IDs on tasks describes.

An approval bot

An approval bot finds its tasks with List Tasks and approves them with Perform Task Action. A token acts as its user, so a bot sees and acts on the same tasks its user can. Which tasks you can see lists the rules for each role and kind of assignment. A bot running as the current approver can read the request with Get Access Request, using the task’s access_request_id. Once the request no longer waits on the bot, the bot needs another way to see it, as Who can see a request describes. This script approves requests for a list of apps and leaves every other request for a person:

Approval bot

import os
import time

import requests

BASE_URL = "https://api.lumos.com"
POLL_SECONDS = 60

# Requests for these apps are approved. Everything else is left for a person.
AUTO_APPROVE_APP_IDS = {"1a2b3c4d-5e6f-7890-abcd-ef1234567890"}

# Error codes that mean someone already handled the task. Any other error stops the bot.
ALREADY_HANDLED = {
    "task.already_in_status",
}

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['LUMOS_API_TOKEN']}"


def pending_approval_tasks(user_id):
    """Yield the pending approval tasks assigned to user_id, with the actions that user can take."""
    params = {
        "assigned_user_ids": user_id,
        "type": "access-request-approval",
        "status": "pending",
        "expand": "actions",
        "page_size": 100,
    }
    while True:
        response = session.get(f"{BASE_URL}/v1/tasks", params=params)
        response.raise_for_status()
        page = response.json()
        for task in page["tasks"]:
            if task["type"] == "access-request-approval" and task["status"] == "pending":
                yield task
        token = page.get("next_page_token")
        if not token:
            return
        params["page_token"] = token


def should_approve(task):
    return task["app"] is not None and task["app"]["id"] in AUTO_APPROVE_APP_IDS


def approve(task, action):
    """Approve a task. Returns False if someone else handled it first."""
    body = {
        "action_type": action["action_type"],
        "transition_to": action["transitions"][0]["transition_to"],
    }
    response = session.post(f"{BASE_URL}/v1/tasks/{task['id']}:perform-action", json=body)
    if response.status_code in (400, 409):
        if response.json().get("error", {}).get("code") in ALREADY_HANDLED:
            return False
    response.raise_for_status()
    return True


def run_once(user_id):
    for task in pending_approval_tasks(user_id):
        if not should_approve(task):
            continue
        # The list only offers the actions the bot's user can take.
        action = next(
            (a for a in task["actions"] if a["action_type"] == "approve-access-request"),
            None,
        )
        if action is None:
            continue
        if approve(task, action):
            print(f"Approved task {task['id']}")
        else:
            print(f"Task {task['id']} was already handled")


me = session.get(f"{BASE_URL}/v1/users/current")
me.raise_for_status()
user_id = me.json()["id"]
while True:
    run_once(user_id)
    time.sleep(POLL_SECONDS)

Run it with the token in the environment:

export LUMOS_API_TOKEN='lsk_your_token'
python approval_bot.py

A misspelled filter returns 400 rather than a wider list, as Filtering the list describes. The bot checks each task’s type and status before it acts. Manager approvals are access-request-approval tasks too. Some older manager approvals that are still open have the type manager-approval instead. List that type as well if the bot should handle them.

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

Access requests and tasks

How a request moves

File a request and follow it

The tasks on a request

An approval bot

​How a request moves

​File a request and follow it

​The tasks on a request

​An approval bot

How a request moves

File a request and follow it

The tasks on a request

An approval bot