Authentication

Every request to /api/v1 carries a bearer token:

curl https://lunary.cloud/api/v1/instances \
  -H "Authorization: Bearer lc_your_token_here"

Minting a token

Tokens are minted in the dashboard under Access → API tokens. A token belongs to your organization, carries an explicit set of scopes, and can have an expiry. The token value starts with lc_ and is shown once; we store only a hash.

Access is one choice, not a per-scope picker: Read-only, Read + write if your own role holds write scopes, and Pull images only for a docker login. Either grant is intersected with the scopes you hold, so a token can never exceed its creator. Mint read-only for status pages and monitoring.

Scopes

Scope	Grants
read_instances	List and read your instances, their health, the catalog you can deploy from, your registry credentials, your domains and hostnames, and your Lunary registry and its images.
write_instances	Provision, update, rename and tear down instances; store and delete registry credentials; add, verify and remove domains and hostnames. Also reads the runs those writes return (GET /runs/{id} for an instance's apply, redeploy or teardown run), so a provisioning token can poll what it started without read_plugs.
read_plugs	Read plugs, runs, routines, and artifact download URLs.
write_plugs	Trigger plugs; create, update, delete, and run routines.
read_billing	Read subscription, payment method, and invoices.
push_images	Push, pull and delete tags of your organization's images in the Lunary registry, registry.lunary.cloud/<org>/<name>, with docker login registry.lunary.cloud using the token as the password. See Registry.
pull_images	Pull your organization's images from the Lunary registry, and nothing else: the docker login for a server outside Lunary. Not part of Read-only; minted as Pull images only.

Errors

• 401 unauthorized: the token is missing, malformed, expired, or revoked.
• 403 insufficient_scope: the token is valid but lacks the scope the endpoint requires; details.required names it.
• 429 rate_limited: over budget for this class of request (reads and writes are metered separately). Retry-After gives the wait in seconds; every response carries X-RateLimit-Limit and X-RateLimit-Remaining.

Each endpoint's required scope is listed in the API reference, which is generated from the same OpenAPI document the server enforces.

OAuth for MCP clients

The MCP endpoint also accepts OAuth access tokens issued by our sign-in provider, so an MCP client can log in through the browser instead of pasting a token. REST endpoints accept lc_ tokens only.