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 or regenerate, and apikeys:delete to revoke. If an action is missing, your role is lacking the matching permission or the feature is off for your plan.

A Pro-plan feature

Creating and renaming API keys requires the Pro plan - feature:apikeys is enabled on Pro and locked on the Free plan.

Downgrading never strands a live key. If your account moves off Pro, any keys you already created keep working - the credential is not revoked. So that you are never locked out of a live credential, the API Keys page stays reachable in a locked state: you can still view and revoke your existing keys, but Create, Rename and Regenerate are disabled with an upgrade hint until you return to Pro. This mirrors the API itself: apikeys:read and apikeys:delete stay available on a plan-locked account, while apikeys:create and apikeys:edit (which also gates regenerate) are rejected on both the GraphQL and REST endpoints.

Finding the page after a downgrade. Because feature:apikeys is off on your plan, the API Keys entry is hidden from the sidebar (like every other feature you do not have). The page itself is still reachable - if your account still holds any live keys, the Subscription page shows a notice linking straight to it so you can view and revoke them. You can also open /dashboard/api-keys directly.

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 carry. The picker lists the full permission registry, grouped by category with a search box; scopes you do not currently hold are shown disabled. A personal key can additionally carry the user-scoped permissions (the Ideas Hub family), since it acts as you.
• Rename - the pencil icon changes the display name only; the key material, its permissions, and its expiry are fixed once minted.
• Regenerate - the circular-arrows icon rotates the key's secret in place. The name, permissions and expiry stay the same, but the old secret stops working immediately and a brand-new key is shown once. A confirmation step names the key and warns that anything still using the old secret breaks until you update it. Use it when a key leaks - you recover without a support ticket and without losing the key's configuration.
• 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 from the same grouped, searchable picker. Because a service key carries no member identity, it offers only account-scoped permissions - the user-scoped (Ideas Hub) family is not shown, unlike the personal-key picker.
• Rename - changes the display name only; permissions, key material, and expiry are immutable once minted.
• Regenerate - rotates the key's secret in place (name, permissions and expiry unchanged). The old secret stops working immediately and the new key is shown once, behind a confirmation step that warns every consumer using the old key will break. Rotate a leaked deploy key without recreating and re-scoping it.
• 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).

Developer keys (lm_dev_…)

Developer keys are managed separately, under Account → Developer → API keys (not on the Manage → API Keys page above), because they are a developer credential rather than an account one. They are the key lumio deploy and CI pipelines use to publish extensions, and they behave differently from personal and service keys:

• Bound to a developer identity, not an account. A developer key is owned by either your developer profile or a developer team - never an account and never a member. Like a service key it keeps working after the member who minted it leaves a team.
• Not tied to your plan. Eligibility is approved-developer status - an approved developer profile or membership of a developer team - not the Pro plan. Free-tier developers can create developer keys even when the feature:apikeys page above is Pro-only.
• Scoped to extension-dev:* only. The scope picker offers only the extension-developer family - read, create, edit, delete, publish, analytics, payouts. A developer key can never carry an ordinary account scope (such as chat:ban).
• Profile vs. team. When creating a key you choose an Owner: your own developer profile, or any team where you hold the team-secrets:edit right. Teams you belong to without that right are not offered - the backend enforces the same rule. You can see every key across your profile and your teams, but can only rename or revoke a team's keys when you hold team-secrets:edit for that team.
• Create / rename / revoke work exactly like the other kinds: the full key is shown once on creation, rename changes the display name only, and revoke stops the key immediately.

Developer key lifecycle actions are recorded in the audit log as user-scoped events (user:developer_api_key_created, user:developer_api_key_updated, user:developer_api_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. The card afterwards shows only the key's short prefix (for example lm_svc_ab…), never the secret.

Regenerating a key reveals its new secret exactly the same way - once, with a Copy button - and the previous secret is invalid from that moment on. So if you lose a secret you no longer have to revoke and recreate the key: Regenerate it instead, keeping the same name, permissions and expiry.

What scopes a key can carry

The picker renders the account's full permission registry - the same catalogue used by the role editor - grouped by category with a search box, rather than a short curated list. This lets a key do everything the channel or user behind it can, which is the whole point of an API key.

• Personal keys offer account-scoped permissions and the user-scoped Ideas Hub family (ideas:*), because a personal key acts as the member who created it.
• Service keys offer account-scoped permissions only - they have no member identity, so user-scoped permissions would be meaningless.

A small set of scopes is never assignable to any key, regardless of what its creator holds, because a bearer credential that can carry them is too dangerous:

• apikeys:create and apikeys:edit - a key that can mint or manage other keys would outlive the human it belongs to.
• tokens:create - minting popout tokens.
• account:delete - deleting the account a key deploys to.

These are the only exclusions; everything else in the registry is offered. The scope list a picker offers is fetched live from the backend (apiKeyAssignablePermissions), so it always matches what the API will actually accept - the picker and the API can never drift.

Permission subset limit

The picker 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 immutable after creation: renaming a key changes its display name only, never its scopes. To change what a key can do, revoke it 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.