API Keys

Create keys for programmatic access to the Lumio API and the lumio CLI. Manage → API Keys holds two separate sections: Personal keys tied to your own membership, and account Service keys that outlive it.

Two kinds of key

Both kinds are bearer credentials that authenticate REST and GraphQL requests, carry an explicit permission set, and are shown in full only once when created. They differ in who owns them and what happens when a member leaves.

	Personal key	Service key
Prefix	lm_usr_…	lm_svc_…
Owned by	You, within the active account	The account
Bound to a member	Yes — the member who created it	No member identity at all
Survives member departure	No — stops working when you leave	Yes — keeps working after its creator leaves
Best for	Your own scripts, notebooks, the CLI	CI/CD pipelines, servers, long-lived integrations

Both sections live on the same page and share the same access gate: the feature:apikeys feature must be enabled for your plan, and each action is guarded by the apikeys:* permission family — apikeys:read to view keys, apikeys:create to create, apikeys:edit to rename, and apikeys:delete to revoke. If the page is hidden or an action is missing, your role is lacking the matching permission or the feature is off for your plan.

Personal keys (lm_usr_…)

A personal key is bound to you within the current account. Use it for your own scripts and for signing in to the lumio CLI.

• Member-bound lifetime. A personal key stops authenticating the moment you are no longer a member of the account. If you leave — or an admin removes you — your personal keys for that account are purged and can no longer be used. This is the deliberate contrast with service keys below.
• Create — click Create API key, give it a Name, optionally set an Expires date (leave it empty for no expiry), and tick the permissions the key may use.
• Rename — the pencil icon changes the display name only; the key material, its permissions, and its expiry are fixed once minted.
• Revoke — the trash icon deletes the key. Any script using it stops working immediately, and this cannot be undone.

Service keys (lm_svc_…)

A service key is owned by the account, not by you. It carries no member identity, so it keeps working even after the member who created it leaves the team — which is exactly what you want for a deploy bot, a server, or a scheduled job that must not break when someone offboards.

• Survives member departure. Revoke a service key manually once it is no longer needed — it will not stop on its own when its creator leaves. A card whose creator has since left the account is labelled Created by a member who has left the account; the key itself keeps working.
• Create — click Create service key, give it a Name, optionally set an Expires date, and tick the permissions. The dialog shows the same permission list as personal keys.
• Rename — changes the display name only; permissions, key material, and expiry are immutable once minted.
• Revoke — deletes the key. Any server or automation using it stops working immediately, and this cannot be undone.

Service key lifecycle actions are recorded in the audit log as account-scoped events (account:service_key_created, account:service_key_updated, account:service_key_revoked).

The one-time reveal

When you create either kind of key, the full secret is shown once, on the creation dialog's final screen, with a Copy button. Copy it before pressing Done — Lumio stores only a hash of the key, so it can never be shown again. If you lose it, revoke the key and create a new one. The card afterwards shows only the key's short prefix (for example lm_svc_ab…), never the secret.

Permission subset limit

The permission picker in the create dialog only lets you select permissions you currently hold. A permission outside your own access is shown disabled, and the backend enforces the same rule on both the GraphQL and REST APIs — a request for a permission the creator does not hold is rejected. A key can therefore never grant more access than the person who minted it. Permissions are fixed at creation; to change them, revoke the key and create a new one with the set you want.

Using a key

Send the key as a bearer token on the Authorization header of any REST or GraphQL request:

Authorization: Bearer lm_svc_xxxxxxxxxxxx

The same header works for a personal lm_usr_… key. The lumio CLI stores your personal key for you after lumio login. See the REST API and GraphQL references for endpoints, and Auth for how the request is authenticated.

Security notes

• An API key is a bearer credential — anyone holding it has the access it carries. Treat it like a password.
• Grant the minimum permissions the integration needs, and set an expiry where the key only needs to be short-lived.
• Revoke immediately if a key leaks or an integration is retired. For service keys, revoke on offboarding as part of your checklist — they do not expire on member departure.
• Never paste a key into a public chat, ticket, screenshot, or committed source file.