API authentication

Workspace API keys and JWT login for the public HTTP API.

Lunnoa Automate exposes its REST API (Swagger at /docs) to two kinds of callers:

Machines: server-side applications authenticating with a workspace-scoped API key (lna_…).
Humans: end users authenticating with a JWT obtained through the normal login flow (/api/auth) or SSO (/api/sso).

Both converge on the same authorisation model: RBAC permissions evaluated per workspace. There are no separate partner API endpoints.

API keys are service accounts

An API key is a credential for a machine service account: a user of type SERVICE_ACCOUNT that

has no password and can never log in interactively,
is a member of exactly one workspace, chosen when the key is created,
holds a normal RBAC role (system or custom),
is excluded from SCIM and from people-facing user lists,
can never hold the SUPER_ADMIN platform role; /api/admin/* endpoints remain JWT-only.

Every action performed with the key is attributed to the service account in audit trails.

Open Admin Space
Go to Admin Space → API Keys (/adminspace/api-keys).
Create the key
Choose a name, the target workspace, an RBAC role with the minimum permission set, and an optional expiry.
Copy the secret once
Copy the lna_… secret from the confirmation screen. It is shown exactly once; only its sha256 hash is stored.

Send the secret as a bearer token:

request.sh

curl https://your-deployment.example/api/workflows \-H "Authorization: Bearer lna_your_secret_here"

GET/api/workflows

Example authenticated list call

Requires a bearer token (API key or JWT). Outside the role's permissions returns 403; revoked or unknown keys return 401.

Pattern	Who authenticates	When to use
A. Backend holds the key	The custom app's server, as the service account	Background jobs, data sync, server-rendered pages
B. End users are Lunnoa users	Each end user via JWT/SSO	Per-user shares, permissions, and task history

Only the sha256 hash of a key is stored; treat the plaintext like any other production secret.
A leaked key exposes at most one workspace, bounded by the service account's role.
Rotate by creating a new key, switching the application, then revoking the old one.
Set API_KEYS_ENABLED=false to reject all lna_ tokens (fail closed) without affecting human JWT logins.

bash

# .env — enabled by default
API_KEYS_ENABLED=true

Browse every public operation on the API reference, or open Swagger at /docs on your deployment to try calls interactively.