Credentials and scopes

Every credential kind Cloud issues, its prefix, the scopes it can carry, who issues it and how it is revoked, with the scope names the API checks.

One reference for every credential#

LumenFlow Cloud issues several kinds of credential. Each has a fixed prefix, a closed set of scopes, a way to be issued and a way to be revoked. This page is the reference. The developer guide and the security page link here, so they describe the same model.

A credential is refused with 401 when it is unknown or revoked. A request the credential is not scoped for is refused with 403, and the refusal names the scope it needed (see Scope rules below).

Credential kinds#

Kind	Prefix	Scopes it can carry	Issued by	Revoked by
Workspace API key	`lf_`	`read`, `write`, and the opt-ins `model_config:write`, `limits:write`, `runners:manage`	`POST /api/v1/workspaces/{workspaceId}/api-key`, which issues or regenerates the key, for a signed-in owner or admin	`DELETE /api/v1/workspaces/{workspaceId}/api-key`
Org service token	`lf_org_`	`read` by default, and the opt-ins `workspaces:manage` and `members:manage`	`POST /api/v1/orgs/{orgId}/service-tokens`, by an org owner or admin	`DELETE /api/v1/orgs/{orgId}/service-tokens/{tokenId}`
Inference key	`lf_inf_`	`inference:invoke` only	`POST /api/v1/workspaces/{workspaceId}/inference-keys`	`DELETE /api/v1/workspaces/{workspaceId}/inference-keys/{keyId}`
App key	`lf_app_`	`payments:checkout.create`, `entitlements:read`, `app_connectors:invoke`, `tool_connections:read`, `tool_connections:connect`	`POST /api/v1/workspaces/{workspaceId}/app-keys`, with the narrowest set of scopes you need	`DELETE /api/v1/workspaces/{workspaceId}/app-keys/{keyId}`
Runner onboarding grant	`lf_rog_`	The seven `runner:onboard.*` scopes listed below	`POST /api/v1/workspaces/{workspaceId}/runner-onboarding/grants`, with a lifetime of 7 to 30 days (7 by default)	`DELETE /api/v1/workspaces/{workspaceId}/runner-onboarding/grants/{grantId}`
Engagement token	not a `lf_` key	Read-only, one engagement, filtered by its visibility policy	Per-engagement provisioning in the dashboard	From that engagement's settings
Dashboard session	not a key	UI actions for the signed-in user	Sign-in to the dashboard	Ends when the sign-in session ends

The revoke paths take effect as follows.

Workspace API key. Other instances of the service may keep accepting the old key for up to 15 seconds. The instance that revoked it stops accepting it at once.
App key and runner onboarding grant. Refused on their very next use. Neither is served from a cache.
Org service token. Refused on the instance that revoked it at once. Other instances honour it for up to 15 seconds.

A workspace key may revoke only the inference keys, app keys and runner onboarding grants it issued in its own workspace. An app key, an inference key and a runner onboarding grant revoke nothing.

Scope rules#

Read and write. read covers the safe methods, GET, HEAD and OPTIONS. write covers every other method. Neither implies the other.
Opt-in scopes. model_config:write, limits:write, runners:manage, workspaces:manage and members:manage are never given by default. You name them when you issue or rotate the credential. None of them implies read or write.
Fixed sets. An inference key carries exactly inference:invoke. An app key never carries read or write. A runner onboarding grant carries only runner:onboard.* scopes and is accepted only by the runner onboarding endpoints. Any other route answers a grant with 403 runner_onboarding_grant_not_accepted.
Org tokens never write. An org service token cannot hold write. It can rotate a workspace's primary key with an explicit scope selection, but it cannot hold those scopes itself.
Unknown scopes fail closed. A scope the credential was not issued with grants nothing. Anything not in the list below is refused.
Existing keys. A workspace key created before scopes existed keeps read and write. Choose narrower scopes when you create or regenerate a key, for example read only for a dashboard integration.

A refused request returns 403 with this body:

{
  "error": "This credential does not carry the \"write\" scope required for this request.",
  "reasonCode": "insufficient_scope",
  "requiredScope": "write",
  "grantedScopes": ["read"]
}

Each refusal is written to the audit log.

Scope reference#

Scope	Carried by	What it allows
`read`	Workspace API key, org service token	Read requests for the key's workspace, or for the token's organisation.
`write`	Workspace API key	Every request that changes state, for the credential's workspace.
`model_config:write`	Workspace API key (opt-in)	Manage the workspace's own model routes.
`limits:write`	Workspace API key (opt-in)	Set the workspace's and its inference keys' self-service limits, within the plan and platform ceilings.
`runners:manage`	Workspace API key (opt-in)	Issue and revoke runner onboarding grants for the workspace.
`workspaces:manage`	Org service token (opt-in)	Create, list and archive workspaces of its own organisation, and rotate their primary keys.
`members:manage`	Org service token (opt-in)	Invite, list, change the role of and remove members of its own organisation's workspaces. It never assigns or removes the owner role.
`inference:invoke`	Inference key	Make governed inference calls. See Governed inference API.
`payments:checkout.create`	App key	Create a checkout for the app.
`entitlements:read`	App key	Read the entitlements of the app.
`app_connectors:invoke`	App key	Invoke an app connector.
`tool_connections:read`	App key	Read the outcome of a tool connection attempt and the app's own connections.
`tool_connections:connect`	App key	Start a tool connection attempt for the app.
`runner:onboard.policy.read`	Runner onboarding grant	Read the onboarding policy.
`runner:onboard.code.mint`	Runner onboarding grant	Mint a pairing code for a runner.
`runner:onboard.runner.read`	Runner onboarding grant	Read the runners onboarded under the grant.
`runner:onboard.capabilities.approve`	Runner onboarding grant	Approve the capabilities a runner requests.
`runner:onboard.request.read`	Runner onboarding grant	Read onboarding requests.
`runner:onboard.runner.revoke`	Runner onboarding grant	Revoke an onboarded runner.
`runner:onboard.receipt.read`	Runner onboarding grant	Read onboarding receipts.

Who am I#

GET /api/v1/auth/whoami returns the kind, id, prefix, org, workspace, scopes and name of the credential you present. Any credential may call it, and it never returns a secret or a hash. For a dashboard session it returns the user id and the organisations the user belongs to. expires_at is null for every credential kind.