API keys for your customers

apikeys lets your customers call your app from their own code: scoped, rotating, revocable keys per tenant, rate limited and audited. The secret is shown once and only its digest is stored.

It belongs to one tenant, carries scopes that are your own access permissions, rotates without downtime and revokes within seconds. Do not build your own: key hashing, constant-time compare and redaction are easy to get wrong. It runs inside your app and is free.

The module is built and tested against the local and SQLite stores (spec apikeys). Cloud-side checks and hosted key drivers are planned.

apikeys:
  driver: db
  prefix: acme
  header: x-api-key
  scopes: [orders.read, orders.write, reports.export]
  max-ttl: 365d
  role: member                         # the role a key's principal carries
  limits:
    default: 600/min

import { apikeys } from "mainsdk";

// a signed-in admin issues a key; the secret is shown once
const { key, secret } = await apikeys.create({ name: "CI", scopes: ["orders.read"] });

// in the customer-facing API
const { tenant, scopes } = await apikeys.verify(req);

import { createTestApp, withApiKey } from "@mainsdk/testing";
import { apikeys } from "mainsdk";

const app = createTestApp({ yaml: "schema: 1\nproject: prj_test\ntenancy:\n  resolve: [apikey]\napikeys:\n  prefix: acme\n  scopes: [orders.read]\n" });
const tenant = await app.tenancy.create({ name: "Acme", region: "eu" });
const key = await app.apikeys.issue({ tenant: tenant.id, scopes: ["orders.read"] });

const { scopes } = await apikeys.verify(withApiKey(new Request("http://x/"), key));   // ["orders.read"]
app.apikeys.toHaveAudited("apikey.created");

apikeys:
  driver: db

Quick start

apikeys:
  prefix: acme
  scopes: [orders.read, orders.write]

import { apikeys } from "mainsdk";

// runs in the signed-in tenant; the caller needs the apikeys.manage permission
export async function POST() {
  const { key, secret } = await apikeys.create({ name: "CI", scopes: ["orders.read"] });
  return Response.json({ id: key.id, secret });   // the only time the secret is shown
}

import { apikeys } from "mainsdk";

export async function GET(req: Request) {
  const { tenant, scopes } = await apikeys.verify(req);   // throws MAIN-APIKEY-0001 or -0002 (401) for a bad key
  return Response.json({ tenant: tenant.id, scopes });
}

A key looks like acme_live_eu_<43 characters><6-character checksum>: the prefix, the environment, the tenant's region, 32 random bytes and a CRC32 checksum. A typo or a key from another app fails offline, with no lookup.

Configuration

apikeys:
  driver: db                    # db (default) | local (tests and local mode)
  prefix: acme                  # 2 to 12 lowercase letters and digits; default: the app name
  header: x-api-key             # read when there is no Authorization: Bearer header
  scopes: [orders.read, orders.write, reports.export]
  max-ttl: 365d                 # the longest expiry allowed, and the default
  limits: { default: 600/min }  # per key; create({ rate }) may lower it

What you get

API_KEY_DDL (an array of SQL strings) is a constant, not a function.

Examples

Read and verify a key

apikeys.verify(req) reads Authorization: Bearer first, then the header you set. It returns the tenant, the scopes and the key id. Put apikey under tenancy.resolve and the request runs in the key's tenant without a call from you.

import { apikeys } from "mainsdk";

export async function GET(req: Request) {
  const { tenant, scopes, keyId } = await apikeys.verify(req);
  return Response.json({ tenant: tenant.id, scopes, keyId });
}

A key never widens what the policy allows. An action whose permission is not among the key's scopes fails with MAIN-APIKEY-0003. A test key in production, or a live key anywhere else, fails with MAIN-APIKEY-0007 before any lookup.

List, rotate and revoke

import { apikeys } from "mainsdk";

const page = await apikeys.list({ limit: 25 });          // { items, next? }; no secret, no digest

// the old key keeps working for 24 hours, then expires; the new key comes back with its own secret
const keyId = page.items[0].id;
const { key: next, secret } = await apikeys.rotate(keyId, { overlap: "24h" });

await apikeys.revoke(keyId, { reason: "leaked in a public repo" });   // within 5 seconds everywhere

The overlap is 24 hours unless you set it, and 30 days at most. Revoke is safe to repeat. Rotating a revoked or expired key fails with MAIN-APIKEY-0009. A key id from another tenant fails with MAIN-APIKEY-0012.

Errors and checks

The full list is in check codes.

Swapping drivers

apikeys:
  driver: local   # was db; tests and local mode only

mainsdk check --env prod refuses local with MAIN-CHECK-0026. The spec names this driver memory; the code reads local, the name every other interface uses, and check refuses both.

Testing

When main.yaml has an apikeys section, createTestApp adds app.apikeys.issue({ tenant, scopes }), which skips the permission checks and returns the secret, withApiKey(req, key) to attach it to a request, and app.apikeys.toHaveAudited(action) to assert an audit record such as apikey.created. See the testing kit.

import { createTestApp, withApiKey } from "@mainsdk/testing";
import { apikeys } from "mainsdk";

const app = createTestApp({ yaml: "schema: 1\nproject: prj_test\ntenancy:\n  resolve: [apikey]\napikeys:\n  prefix: acme\n  scopes: [orders.read]\n" });
const tenant = await app.tenancy.create({ name: "Acme", region: "eu" });
const key = await app.apikeys.issue({ tenant: tenant.id, scopes: ["orders.read"] });

const { scopes } = await apikeys.verify(withApiKey(new Request("http://x/"), key));   // ["orders.read"]
app.apikeys.toHaveAudited("apikey.created");

Security and privacy

• Only the SHA-256 digest is stored. The key has 256 bits of entropy, so a fast hash is as safe and keeps verify fast.
• Digests are compared in constant time. Unknown, revoked and expired keys get the same response.
• The log redactor replaces your key format with acme_live_eu_[redacted:apikey] in logs, errors and traces.
• Last use is kept in memory and written once a minute, never in the request path. A verified key is cached for 5 seconds, so a revoke reaches every instance in that time.
• When the store is down, keys verified in the last 15 minutes are served from memory. Others get a retryable 503.

FAQ

Can a key never expire? No. Raise max-ttl if you need a longer life, and rotate with an overlap.

Are these the keys for MainSDK Cloud? No. These are keys your app issues to its customers.

Can a key carry orders.*? Not yet. List each scope.

Next

• Tenants: how a verified key sets the tenant.
• Permissions: the permissions behind scopes.
• Rate limits and quotas: the per-key limit.