Let your customers create API keys.

{
  "effect":    "allow",
  "actions":   ["auth.tenant.api_keys.introspect", "auth.tenant.api_keys.configure"],
  "resources": ["pcft:heimdall:app/<app-uuid>"]
}

curl https://api.auth.productcraft.co/acme/v1/tenant-api-keys/introspect \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -d '{ "key": "pctk_live_4fQ2aZ..." }'

# Active
{
  "active": true,
  "key_id": "8b1c…", "display_id": "tak_3a9f2b1c0d4e",
  "tenant_id": "5e2a…", "tenant_display_id": "tnt_3a9f2b1c0d4e",
  "name": "CI e2e",
  "scopes": ["disputes.read", "audit.read"],
  "created_by": { "account_id": "c41d…", "tenant_role": "agent_full" },
  "expires_at": "2027-01-21T10:00:00.000Z",
  "env": "live"
}

# Anything else: unknown, malformed, revoked, expired, creator gone,
# tenant not active, keys suspended, or a key of another app
{ "active": false }

// tenant-api-keys.ts: verify a tenant API key presented to YOUR API.
import { createHash } from 'node:crypto';

const AUTH_URL = 'https://api.auth.productcraft.co';
const APP_SLUG = process.env.AUTH_APP_SLUG!;
const PAK = process.env.PRODUCTCRAFT_PAK!; // pcft_live_…, holds auth.tenant.api_keys.introspect

const POSITIVE_TTL_MS = 30_000;   // never more than 30 s, never past expires_at
const NEGATIVE_TTL_MS = 60_000;
const MAX_IN_FLIGHT = 8;          // introspect calls in flight per process
const FAILED_VERIFY_BUDGET = 60;  // unknown keys per minute per process
const TIMEOUT_MS = 2_000;

export type Verdict =
  | { active: false }
  | {
      active: true;
      key_id: string;
      display_id: string;
      tenant_id: string;           // the same tenant id your end-user tokens carry as org_id
      tenant_display_id: string;
      name: string;
      scopes: string[];
      created_by: { account_id: string; tenant_role: string };
      expires_at: string;
      env: 'live' | 'test';
    };

/** Auth could not give a verdict. Fail closed: refuse the request, cache nothing. */
export class VerifyUnavailable extends Error {}

// ---- 1. Typo filter (shape + CRC32 checksum). Not a security control. ----
const KEY_PATTERN = /^pctk_(live|test)_[0-9A-Za-z]{43}_[0-9A-Za-z]{6}$/;
const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
  let c = n;
  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
  return c >>> 0;
});

function crc32(s: string): number {
  let crc = 0xffffffff;
  for (let i = 0; i < s.length; i++) crc = CRC_TABLE[(crc ^ s.charCodeAt(i)) & 0xff] ^ (crc >>> 8);
  return (crc ^ 0xffffffff) >>> 0;
}

function base62(n: number, width: number): string {
  let out = '';
  while (n > 0) {
    out = BASE62[n % 62] + out;
    n = Math.floor(n / 62);
  }
  return out.padStart(width, '0');
}

export function isWellFormedTenantKey(key: string): boolean {
  if (!KEY_PATTERN.test(key)) return false;
  return base62(crc32(key.slice(10, 53)), 6) === key.slice(-6);
}

// ---- 2. Cache, single-flight, in-flight cap, failed-verify budget. ----
const cache = new Map<string, { verdict: Verdict; until: number }>();
const inFlight = new Map<string, Promise<Verdict>>();
let budgetWindow = Date.now();
let failedInWindow = 0;

export async function verifyTenantKey(key: string): Promise<Verdict> {
  if (!isWellFormedTenantKey(key)) return { active: false };

  const hash = createHash('sha256').update(key).digest('hex'); // never cache by the raw key
  const now = Date.now();
  const hit = cache.get(hash);
  if (hit && hit.until > now) return hit.verdict;
  cache.delete(hash);

  const pending = inFlight.get(hash);
  if (pending) return pending; // concurrent requests with one key share one call

  if (now - budgetWindow >= 60_000) {
    budgetWindow = now;
    failedInWindow = 0;
  }
  // Budget spent (someone is spraying random keys): refuse unknown keys
  // without calling Auth. Keys already cached as active keep working.
  if (failedInWindow >= FAILED_VERIFY_BUDGET) return { active: false };
  if (inFlight.size >= MAX_IN_FLIGHT) throw new VerifyUnavailable('verify capacity');

  const call = introspect(key)
    .then((verdict) => {
      const at = Date.now();
      if (verdict.active) {
        const until = Math.min(at + POSITIVE_TTL_MS, Date.parse(verdict.expires_at));
        cache.set(hash, { verdict, until });
      } else {
        failedInWindow += 1;
        cache.set(hash, { verdict, until: at + NEGATIVE_TTL_MS });
      }
      return verdict;
    })
    .finally(() => inFlight.delete(hash));
  inFlight.set(hash, call);
  return call;
}

async function introspect(key: string): Promise<Verdict> {
  let res: Response;
  try {
    res = await fetch(AUTH_URL + '/' + APP_SLUG + '/v1/tenant-api-keys/introspect', {
      method: 'POST',
      headers: { authorization: 'Bearer ' + PAK, 'content-type': 'application/json' },
      body: JSON.stringify({ key }), // the key goes in the body, never in a header
      signal: AbortSignal.timeout(TIMEOUT_MS),
    });
  } catch {
    throw new VerifyUnavailable('introspect unreachable');
  }
  if (res.status === 200) return (await res.json()) as Verdict;
  // 429 (your app's introspect bucket), 5xx, or 401/403 (a PAK problem) are
  // not verdicts. Never cache them as {active:false}.
  throw new VerifyUnavailable('introspect answered ' + res.status);
}

curl https://api.auth.productcraft.co/acme/v1/tenant-api-keys/tak_3a9f2b1c0d4e/status \
  -H 'authorization: Bearer pcft_live_...'

{ "status": "revoked", "revoke_reason": "member_removed" }
# status: active | expired | revoked | orphaned | suspended
# revoke_reason: manual | rotated | member_removed | tenant_deleted | null

// Accept tenant API keys only on routes that opt in (Express shown).
import type { NextFunction, Request, Response } from 'express';
import { verifyTenantKey, VerifyUnavailable } from './tenant-api-keys';
import { permissionsOfTenantRole } from './permissions'; // YOUR role → permission grid

export function acceptsTenantKey(scope: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const header = req.headers.authorization ?? '';
    const bearer = header.startsWith('Bearer ') ? header.slice(7).trim() : '';
    if (!bearer.startsWith('pctk_')) return next(); // not a key: your normal auth runs

    let verdict;
    try {
      verdict = await verifyTenantKey(bearer);
    } catch (err) {
      if (err instanceof VerifyUnavailable) {
        res.setHeader('Retry-After', '5');
        return res.status(503).json({ code: 'AUTH_UNAVAILABLE' });
      }
      throw err;
    }
    if (!verdict.active) return res.status(401).json({ code: 'INVALID_API_KEY' });

    // The ceiling, again: the key's scopes ∩ what its creator's CURRENT role allows.
    const allowed = permissionsOfTenantRole(verdict.created_by.tenant_role);
    const effective = verdict.scopes.filter((s) => allowed.has(s));
    if (!effective.includes(scope)) {
      return res.status(403).json({ code: 'SCOPE_MISSING', scope });
    }

    req.principal = {
      type: 'api_key',
      keyId: verdict.key_id,
      tenantId: verdict.tenant_id,   // map to your tenant exactly like org_id
      scopes: effective,
    };
    next();
  };
}

// requireUser is your existing JWT middleware. It lets a request through when
// req.principal is already set, and REFUSES any other pctk_ bearer:
//   if (bearer.startsWith('pctk_') && !req.principal) return res.status(401)…
app.get('/v1/disputes', acceptsTenantKey('disputes.read'), requireUser, listDisputes);
app.post('/v1/reports', acceptsTenantKey('reports.create'), requireUser, createReport);
// No acceptsTenantKey on /v1/api-keys, /v1/team, billing…: keys cannot reach them.