@frogbotai/plugin-api-keys

Add multiple named, independently revocable API keys to a FrogBot application.

import { apiKeysPlugin } from '@frogbotai/plugin-api-keys';
import { buildConfig } from 'frogbot';

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: databaseAdapter,
  collections: [{ slug: 'users', auth: true, fields: [] }],
  plugins: [apiKeysPlugin()],
});

The plugin adds an api-keys collection, owner-scoped management endpoints, API-key authentication, and default admin controls. frogbot dev generates the admin import map before starting, so the key-creation controls appear on the first load. Create a key in the API Keys admin collection, then authenticate requests with either header:

Authorization: Bearer fb_...
X-API-Key: fb_...

Plaintext keys are returned only when created. The collection stores SHA-256 hashes and supports multiple independently revoked keys per user. Minting and rotating need a signed-in session or a key with canMint: a request authenticated by any other key gets 403, so a leaked key can't leave new keys behind. Keys have canMint off unless a session mints them with data: { canMint: true }. A key minted by a key records it as mintedBy, can have canMint only through it, takes its values for fields other plugins add, and with the AI policy plugin stays inside its model list and monthly cap, its spend counting against that cap. Revoking a key revokes every key below it, unless the call passes cascade: false (revokeApiKey({ ..., cascade: false }), or { "cascade": false } as the revoke endpoint's body), which revokes only that key and leaves the keys it made working. The admin's revoke dialog asks, checked by default, when the key made any. A key rotates only itself and the keys it minted; rotation keeps mintedBy, and a refused one revokes nothing. A key can still list and rename its owner's keys, and revoke itself and the keys it minted.

Keys work until they are revoked, unless minted with expiresAt, an ISO date in the future, posted to mint beside name or passed to mintApiKey. Send a day such as 2027-02-07 (midnight UTC) or a date and time with Z or an offset; any other format, a day that doesn't exist, or a date that isn't in the future gets 400. Once it passes, the key stops authenticating. It can't be changed later, rotation keeps it, and rotating an expired key gets 400. A key minted by a key expires no later than its parent. The create dialog has an Expires day picker, empty by default, with 30 days, 90 days, 1 year and No expiry buttons; the key works through the chosen day.

The plugin adds no budget or model limits; requests use the owner's AI policy. With @frogbotai/plugin-ai-policy on the same auth collection, each key also gets a model list and monthly cap inside its owner's, set in a collapsed Limits section of the create dialog. Other plugins add such fields to the keys collection: mint accepts them as data, rotate copies them from the old key, a key minted by a key takes its parent's values, and server components registered under admin.custom['plugin-api-keys'].createFields render in the dialog's Limits section, reading and setting values with useCreateKeyData() from @frogbotai/plugin-api-keys/client. With AI configured, usage rows include an optional apiKey relationship to the authenticating key. Cookie-authenticated requests omit it, and the relationship follows collectionSlug.

Build and start-only workflows must run frogbot generate:importmap after adding the plugin. Add it as a prebuild step when CI invokes next build directly. If the server console reports a component missing from the import map, run frogbot generate:importmap and rebuild, or restart frogbot dev.

apiKeysPlugin({
  authCollection: 'accounts',
  collectionSlug: 'credentials',
  tokenPrefix: 'acme',
  headerNames: ['x-service-key'],
  collection: {
    admin: { group: 'Security' },
    fields: [{ name: 'environment', type: 'text' }],
  },
});

Collection overrides merge with the generated fields, access, endpoints, hooks, admin components, and transforms applied by other plugins. The manager uses the default admin components, and the token dialog ships a small stylesheet built on the admin theme variables.

The plugin has no role system of its own. Keys are owner-scoped. To layer roles on top, install @frogbotai/plugin-roles and pass canRevokeAnyKey and collection access:

import { allow, hasRole } from '@frogbotai/plugin-roles';

apiKeysPlugin({
  canRevokeAnyKey: (req) => hasRole(req, 'admin', 'support'),
  collection: {
    access: {
      read: allow('auditor', 'support', { role: 'member', own: 'owner' }),
      update: allow('support', { role: 'member', own: 'owner' }),
    },
  },
});