API keys

The API keys plugin adds an api-keys collection, API-key authentication, and admin controls for creating and revoking keys. Each user can own multiple named keys, and each key can be revoked independently.

Install

pnpm add @frogbotai/plugin-api-keys

Configure

Add the plugin to your FrogBot config. By default, it associates keys with the auth-enabled users collection.

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

export default buildConfig({
  collections: [
    {
      slug: 'users',
      auth: true,
      fields: [],
    },
  ],
  plugins: [apiKeysPlugin()],
})

frogbot dev generates the admin import map before starting, so the API Keys collection and its key-creation controls appear on the first load. Click Create API key in the API Keys list toolbar, where Create New sits on other collections, to create a named key, and copy the token when it is displayed. The plaintext token cannot be retrieved again. Build and start-only workflows must run frogbot generate:importmap after adding the plugin. The blank template does this automatically during prebuild; add the same step to custom CI workflows that invoke 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.

Authenticate requests

Send the key as a Bearer token or through the X-API-Key header:

Authorization: Bearer fb_...

X-API-Key: fb_...

The request authenticates as the user who owns the key. Revoked, malformed, and unknown keys do not authenticate. A Bearer key takes precedence; when the Authorization header holds something other than an API key, such as a session token, FrogBot reads the key from the key headers instead. The auth collection’s /me endpoint returns the key owner and never echoes the key back. When AI is configured, usage rows include an optional apiKey relationship identifying the key that authenticated the request. Cookie-authenticated requests omit it, and the relationship follows a custom collectionSlug. On a key-authenticated request, req.user is the owner with apiKeyId and apiKey, the key document without its hash, so hooks and access functions can read fields other plugins add to keys. Other plugins find the keys collection through plugins['plugin-api-keys'].options.collectionSlug (Order, slug, and options).

Configuration options

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

Option	Type	Default	Description
`authCollection`	`string`	`'users'`	Auth-enabled collection whose users own the keys. The plugin throws at startup if the collection is missing or doesn’t have auth enabled.
`collectionSlug`	`string`	`'api-keys'`	Slug for the generated API-key collection.
`tokenPrefix`	`string`	`'fb'`	Prefix placed before generated key values, joined with `_`. Only tokens with this prefix authenticate.
`headerNames`	`string[]`	`['x-api-key']`	Request headers checked for a key when `Authorization` doesn’t carry one. Replaces the default list.
`collection`	`Partial<CollectionConfig>`	—	Collection overrides, including fields, access, hooks, endpoints, and admin configuration.
`canRevokeAnyKey`	`(req: FrogBotRequest) => boolean \| Promise<boolean>`	—	Predicate allowing a request to revoke or rotate a key it does not own. Without it, callers revoke and rotate only their own keys.

Collection overrides merge with the generated configuration and changes made by other plugins. The collection uses the key-round icon in the admin sidebar; set collection.admin.icon to use a different one. The admin controls use the default admin components, and the token dialog ships a small stylesheet built on the admin theme variables.

Budgets and limits

The plugin has no budgets, rate limits, or model limits of its own. A key authenticates as its owner, so requests made with it pass the owner’s ai.access rules. With the AI policy plugin, they use the owner’s models and monthly budget, their spend counts toward the owner’s total, and each key gets its own model list and monthly cap inside the owner’s (API key limits).

Fields from other plugins

Other plugins can add fields to the keys collection, and the plugin keeps them:

mint accepts data, fields the plugin didn’t define, and passes them to create, so their validation runs. The create dialog posts { name, data } and shows validation errors.
rotate copies every field the plugin didn’t define from the revoked key, and runs the create with req.context.apiKeyRotatedFrom set to the revoked key’s ID.
The create dialog renders server components registered under the keys collection’s admin.custom['plugin-api-keys'].createFields in a collapsed Limits section. They read and set the posted data with useCreateKeyData() from @frogbotai/plugin-api-keys/client. With none registered, the dialog has no Limits section.

Role-aware access

The plugin does not require a role system. By default, callers read and update only the keys they own, and revoke and rotate are limited to the caller’s own keys. To layer roles on top, install @frogbotai/plugin-roles and pass role clauses as the collection access:

import { apiKeysPlugin } from '@frogbotai/plugin-api-keys'
import { allow, hasRole, rolesPlugin } from '@frogbotai/plugin-roles'

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

rolesPlugin() with no roles listed is inert and binds nothing, so allow() clauses passed to any plugin deny every request until you list the roles.

Security behavior

Plaintext keys are returned only when created.
The collection stores a SHA-256 hash and a short display prefix, not the plaintext key.
Collection reads are scoped to the authenticated owner by default.
Keys are revoked individually without affecting the owning user’s other authentication methods.
Deleting a user also deletes every key that user owns.
Collection reads and writes, revoke, and rotate are owner-scoped until you widen them.
Minting and rotating need a signed-in session. A request authenticated by an API key gets 403, so a leaked key can’t create keys that outlive revoking it. A key can still list, rename, and revoke keys, including itself.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Install

Configure

Authenticate requests

Configuration options

Budgets and limits

Fields from other plugins

Role-aware access

Security behavior

​Install

​Configure

​Authenticate requests

​Configuration options

​Budgets and limits

​Fields from other plugins

​Role-aware access

​Security behavior

Install

Configure

Authenticate requests

Configuration options

Budgets and limits

Fields from other plugins

Role-aware access

Security behavior