API Keys

Overview

Every request to the Lua API — from the CLI, a device client, or a direct HTTP integration — authenticates with an API key. There are two kinds of key:

Legacy keys

api_ followed by 32 hex characters. Created before scoped keys existed. Act with the owner’s full permissions in every organization the owner belongs to.

Scoped keys

api_<uuid>.<secret>. Personal keys with an explicit role on one or more organizations or agents — never more than the owner could do themselves.

Both kinds are used exactly the same way at request time — see Using a key. The difference is entirely in how much access the key carries.

Legacy keys

If your key was created before scoped keys shipped, nothing about it changes. Legacy keys:

Act with the owner’s full permissions, in every organization the owner belongs to.
Keep working indefinitely.

There is no deprecation date, no forced rotation, and no expiry for legacy keys. You are not required to switch to a scoped key — do it when it’s convenient, e.g. the next time you set up a new integration.

Scoped keys

A scoped key is a personal key: it belongs to one member, and it carries an explicit role on each organization or agent it’s granted against — the same kind of role a human member holds on that resource in the admin dashboard. Two rules govern what a scoped key can do:

Capped at the owner's role

A scoped key can never do more than its owner can. Its effective role on a resource is capped at the owner’s current role there, even if the key was originally granted a broader role.

Follows the owner's access

If the owner loses access to an organization, any key of theirs scoped to that organization loses access too. Keys the owner holds on their other organizations keep working normally.

The role picker in the dashboard (Settings → API Keys) shows the current set of roles you can grant, since it’s the same roster used for human org members. Scope each key to the organizations or agents it actually needs — see Best practices.

Creating a key

Keys are created in the admin dashboard, under Settings → API Keys.

lua admin
# Or visit https://admin.heylua.ai

Open Settings → API Keys

This is a personal section — you’re managing your own keys, or (if you’re an org admin) keys on behalf of another member.

Choose the scope

Grant a role on one or more organizations or agents. An org admin creating a key for another member has the key capped at that member’s role — it can’t exceed what the key’s owner can already do.

Set an optional expiry

Defaults to never. Set a date if the key is for a temporary integration.

Copy the secret

The full secret is shown exactly once, at creation. Store it in a secrets manager or .env file — it can’t be viewed again after you navigate away.

Never commit an API key to version control or share it publicly.

Managing a key

Rotate

Replaces the key’s secret while keeping its role and grants intact. Only the key’s owner can rotate it. The new secret is shown exactly once, the same as at creation — the old secret stops working immediately.

Suspend / reactivate

Temporarily disables a key without losing its configuration. A suspended key fails authentication until it’s reactivated; its role and grants are untouched in the meantime.

Revoke

Permanently disables a key. Either the key’s owner or an org admin can revoke it. Revocation is one-way — a revoked key can’t be reactivated, only replaced with a new one. It takes effect within about a minute everywhere.

Using a key

Usage is identical for legacy and scoped keys:

HTTP API
CLI
Device clients

Authorization: Bearer YOUR_API_KEY

See the HTTP API reference.

export LUA_API_KEY=your-api-key
# or
lua auth configure --api-key your-api-key

See Authentication.

new DeviceClient({
  apiKey: process.env.LUA_API_KEY!,
  agentId: 'your-agent-id',
  // ...
});

See the Devices quickstart.

Errors

Status	Meaning
`401`	The key is invalid, expired, suspended, or revoked.
`403`	The key is valid, but its role doesn’t allow that action on that resource.

A 403 on a scoped key usually means the key needs a broader role, or a grant on an additional organization or agent — check Settings → API Keys in the dashboard.

Best practices

One key per integration

Don’t reuse a single key across unrelated integrations. If one is compromised or needs rotating, a dedicated key limits the blast radius and makes it obvious what to revoke.

Grant the narrowest role that works

Give a key only the role it needs on a resource, not a broader one “to be safe.” A key capped at the right role can’t be misused for actions it was never meant to perform.

Prefer agent-level over org-level scope

If an integration only ever needs one agent, scope the key to that agent instead of the whole organization. It keeps the key from reaching agents it has no business touching.

Set an expiry for temporary access

Contractor access, a one-off migration script, a demo environment — anything with a known end date should get an expiry instead of relying on someone remembering to revoke it later.

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

Legacy keys

Scoped keys

Legacy keys

Scoped keys

Creating a key

Managing a key

Using a key

Errors

Best practices

Next Steps

CLI Authentication

HTTP API

​Overview

Legacy keys

Scoped keys

​Legacy keys

​Scoped keys

​Creating a key

​Managing a key

​Using a key

​Errors

​Best practices

​Next Steps

CLI Authentication

HTTP API

Overview

Legacy keys

Scoped keys

Creating a key

Managing a key

Using a key

Errors

Best practices

Next Steps