API Keys in Your Routes
Accept customer API keys on your own /api endpoints with authorizeApiKey: scope, sessionless path, owner-filtered service and the requests customers send.
The same keys that reach the MCP server can authenticate your own JSON endpoints. The kit ships no REST endpoint for them: you add the ones your product needs. Only API_ACCESS_KEYS has to be on (Turn It On).
Customers create and revoke keys on Settings → API keys (API Keys).
Checklist
To accept keys on a new route, in this order:
- Add a scope.
- Create the route with the generator.
- Mark the path sessionless.
- Authorize in the handler with
authorizeApiKey. - Filter by the account.
- Test it.
When you finish, a customer can call the route with their key and sees only their own account's rows.
How Customers Call It
curl https://your-app.com/api/projects \ -H "x-api-key: $MY_APP_API_KEY"- The key goes in
x-api-keyonly. A request that also sendsAuthorization, or puts a key,api_keyoraccess_tokenin the URL, is refused. - Every request reads live state: a revoked or expired key fails on the next call.
- Refusals are JSON
{ "code": … }with the HTTP status (Request Error Codes). Over the limit:429withRetry-After.
1. Add a Scope
Add it to apiAccessScopes in apps/web/config/api-access.config.server.ts, as in Adding Tools. One catalogue serves routes and MCP tools.
2. Create the Route
pnpm kit:generate route projects --methods get --publicReplace the generated { ok: true } body with the handler in Authorize in the Handler.
Why --public: it skips the generated session check. A key route must not read the browser session too, because one request could carry a cookie and a key for different users.
3. Mark the Path Sessionless
Add the exact path to SESSIONLESS_PATHS in apps/web/lib/sessionless-paths.ts:
export const SESSIONLESS_PATHS = new Set([ // ... '/api/mcp', '/api/projects',]);Why: without it, the session middleware touches the database before the key's rate limit runs.
Never add a prefix.
4. Authorize in the Handler
// apps/web/routes/api/projects.tsimport { defineHandler } from 'void';import { authorizeApiKey } from '#/lib/api-access.server.ts';import { findAccountProjects } from '#/db/projects.server.ts';export const GET = defineHandler(async (c) => { const { account } = await authorizeApiKey({ c, requiredScopes: ['projects:read'], }); return { projects: await findAccountProjects(account) };});Call authorizeApiKey first, before reading a body. It checks the rate limits, the key, its owner, the scopes and your policies, and throws the HTTP refusal itself. It returns:
{ keyId, // the key's id: for audit, never the secret account, // { kind: 'personal' | 'organization', id } scopes, // the key's effective scopes today}5. Filter by the Account
- The query uses
accountas the owner, as in Write the Query and Service. Move real logic into a*.service.ts. - Ignore any user, account or organization id in the request.
- Check every resource id the caller sends against
account.id.
For a write (POST, PUT, DELETE):
- Call
authorizeApiKeyinside that handler too. - Validate the body with
defineHandler.withValidator(API Routes). - Record audit with
recordSystemAudit.
Server clients send no Origin, so the cross-site check doesn't block them.
6. Test It
- Create a key with
projects:readandcurlthe route:200. - No header:
401 API_KEY_REQUIRED. A key without the scope:403 INSUFFICIENT_SCOPE. Revoked:401 INVALID_API_KEY. - Personal and organization keys each see only their own rows.
apps/web/lib/__tests__/api-key-authorization.server.test.ts covers the helper's refusals.