Keys
Create, scope and revoke the service API keys that integrations and AI agents use to call the store.
A service API key lets a program call Litestore when no signed-in person is behind the request. You create one when you connect an integration, an AI agent or an outside assistant over MCP.
Request
Key format
In the code, this key is a ServiceApiKey. The caller sends it as a Bearer token. Every key starts with lsk_, which makes a leaked key easy to recognise when it turns up in a log or a paste.
Litestore stores a SHA-256 hash of the key, not the key itself. The key is shown exactly once, when you create it. It can't be recovered later, because the database has nothing to recover it from.
Scopes
Litestore has six scopes, and a real request path checks each one. The constants file explains why the list only contains scopes that code enforces:
/** Available scopes for service API keys. Only scopes that are actually ENFORCED by a
* request path belong here — advertising a scope no consumer checks (formerly
* `write:catalog`/`write:users`/`admin:delete`) lets operators grant phantom power. */
export const API_SCOPES = [
"read",
"read:cart",
"write:cart",
"write:orders",
"write:webhooks",
"admin:mcp",
] as const| Scope | What it lets the key do |
|---|---|
read | Call read-only oRPC procedures, including listing and reading webhooks. |
read:cart | Read a cart through the cart endpoints. |
write:cart | Create and change a cart. |
write:orders | Write orders through the service surface. |
write:webhooks | Create, update, delete and rotate webhook endpoints. |
admin:mcp | Use the operator MCP endpoint at app/api/mcp/admin. |
Scope list
Litestore removed three scopes: write:catalog, write:users and admin:delete. Nothing in the codebase checked them. Litestore treated a request with write:catalog exactly like a request without it.
An unchecked scope is worse than no scope. If you give a key read plus write:catalog, it looks as if you have drawn a boundary, but the key can do nothing more or less than before. The source comment calls this phantom power.
That is why the list only contains real scopes. A scope belongs on the list only if some request path rejects callers that lack it.
Key management
Only a super-admin can create keys, and they do it in the admin.
Developer settings
Sign in as a super-admin and open the developer settings.
Key and scopes
Give the key only the scopes its caller needs.
Key reveal
Litestore shows the full lsk_ key once. Store it in the integration's secret settings before you close the dialog.
Revocation
Revoking a key sets a flag instead of deleting the row. Litestore reads isActive again on every call instead of caching it with the key, so the very next request with a deactivated key fails. Each successful call also stamps the key's lastUsedAt.
Fast revocation matters when a key has leaked. If Litestore cached the decision, a revoked key would keep working until a session or cache expired. Here, revocation takes effect on the next request.
An admin:mcp key reaches the operator tool kit
Treat a key with admin:mcp like an admin credential, because it can use the admin's AI tools. Each key records who created it (createdById), and every MCP call acts as that admin, with their current role, permission overrides and ban state read fresh on each request. A key whose creator is gone, banned, no longer an admin or lacks ai:view is refused. Its read tools answer directly. Its change tools only create approval cards in that admin's queue, so the key cannot move money on its own.
Rate limiting
Litestore applies rateLimits.publicApi to service endpoints in addition to checking the key. Both MCP routes are rate limited per IP.
The two checks answer different questions. The key check determines whether a caller may make the request at all. The rate limiter determines how often an allowed caller may make it.
Related
oRPC
The oRPC endpoint at /api/rpc manages webhooks for callers with a service key, and it also has a health ping and a scope check on each procedure.
MCP
AI assistants connect to the store over MCP, with public shopper tools at /api/mcp and the admin's gated tool kit at /api/mcp/admin behind an admin:mcp key.
Overview
Litestore signs users in with Better Auth magic links and optional Google OAuth, re-validates sessions, and writes impersonation to the activity log.