Skip to main content
Lumos API v1 authenticates with a bearer token. Send it on every request:
Tokens start with lsk_. There’s no cookie, session, or refresh step. The token alone authenticates each request.

​
Create a token

  1. In Lumos, go to Settings → API Tokens.
  2. Click “Add”.
  3. Enter a name and a description.
  4. Click “Add”.
  5. Copy the token value.
  6. Store the token as a secret that your automation can read.
Lumos shows the value once, when you create the token. If you lose it, create a new token. Then delete the old one.
Treat a token like a password. Keep it out of source control, browser code, and CI logs. Anything that holds the token can act as the user who created it.

​
What a token is allowed to do

A token inherits the permissions of the user who created it. A call returns what that user could see in the Lumos UI, and nothing more. If the admin who created a token later loses a role, the token loses that role’s access too. Automation that depended on that access starts to fail. A read-only token works differently. It can read what a Read Only Admin can, whatever roles its creator has, and it can’t make changes. Create service automation tokens as a Lumos user that exists only for automation. A token that belongs to a person can lose access when that person changes teams or leaves. On read endpoints that support expand, Lumos also checks permissions per field, as Requesting fields with expand describes.

​
Telling the failures apart

Status codes covers every status the API returns.

​
Rate limits

Lumos limits each organization to 100 requests per second and 4,000 requests per minute. Every request made with any of your organization’s API tokens counts toward the same limits, so spreading requests across more tokens doesn’t raise them. A request without a token counts toward a limit for its IP address. Each limit covers a moving window of time. While a limit applies, every response includes these headers, not only a 429: On a successful response, the headers describe the shortest window. On a 429, they describe the limit you went over. A request over the limit returns 429, with code set to rate_limited. Wait the number of seconds in Retry-After, plus a small random delay so that parallel clients don’t all retry at once. When you read in bulk, use larger pages instead of more requests. If you need a higher limit, contact your Lumos representative.