Bearer token
All API requests require a Bearer token in theAuthorization header.
Getting your API key
Create one yourself under Settings → Developer API (app.lumisreach.com/settings/api), or ask us to provision one when your account is set up. Each key is prefixed withlumisreach_ and should be kept secret; the
plaintext is shown once, at creation.
A key created from Settings → Developer API carries no scope restrictions, which means it works on the whole v1 API
and on every MCP server tool — including
Quick Agent Actions — with no further configuration. Keys that
are issued with an explicit scope list are held to it (see below).
API keys are hashed before storage. If you lose your key, you will need to generate a new one.
Key format
Permission scopes
Scopes are opt-in restrictions, in the style of Stripe’s restricted keys. A key issued without any scope is unrestricted. A key issued with a scope list can only reach endpoints covered by it:Tenant scopes
Every API key is also tied to one of three tenant scopes, which controls what resources the key can see:
Tenant isolation is enforced server-side on every endpoint. A sub-entity-scoped key cannot read or write across to a sibling sub-entity or up to the umbrella’s private resources.
To pick the right scope:
- One key for everything? → organization-scoped.
- Vendor needs to manage one location? → sub-entity-scoped. Revoke the key without affecting the rest of the org.
- Solo developer / single-user account? → user-scoped.
Security best practices
- Store API keys in environment variables, never in source code
- Rotate keys periodically — revoke the old key in Settings → Developer API, then issue a new one (plaintext is shown once at creation; we only store the SHA256 hash)
- Use separate keys for development and production
- Use the smallest scope that works — prefer sub-entity-scoped keys for per-location vendor integrations
- Monitor key usage via the account endpoint