nocobase-app-plugin-api-keys

Registers Better Auth API key authentication in a NocoBase App for non-interactive API access.

9|3|Updated Aug 14, 2026
One-click install
npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-api-keys-nocobase
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: nocobase-app-plugin-api-keys
Source: https://github.com/nocobase/nocobase3/tree/main/packages/plugins/app-plugin-api-keys/skills/nocobase-app-plugin-api-keys
Command: npx skills add https://github.com/nocobase/nocobase3 --skill nocobase-app-plugin-api-keys-nocobase

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Scripts, cron jobs, and third-party integrations need to call a NocoBase App's API as a real user without interactive sign-in, and teams need to diagnose why issued keys are rejected. This Skill registers the API Keys plugin so callers authenticate with an x-api-key header that resolves to the key owner's session and roles. ## Core Features & Use Cases - Plugin registration: Wires the server and client plugin halves, the Better Auth apiKey plugin, the apikey table migration, and the Settings page for key management. - Key-based API access: Callers send an x-api-key header and auth.required() resolves the key into the owner's session, so authorization evaluates that user's roles with no route changes. - Troubleshooting rejected keys: Explains Better Auth's 401 KEY_EXPIRED, 401 KEY_NOT_FOUND, and 429 USAGE_EXCEEDED responses, plus the enableSessionForAPIKeys default that must stay on. - Use Case: A cron job needs to sync orders nightly. Register the plugin, grant page:api-keys/access, create a key in the Settings page, and call curl -H 'x-api-key: <key>' against the App's API. ## Quick Start Register the API Keys plugin in my NocoBase App's server and client plugin lists, add apiKey() to the auth config, run the migration, and show me how to call an authenticated route with an x-api-key header.

Frequently Asked Questions about nocobase-app-plugin-api-keys

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add API key authentication to a NocoBase App?▼

Add the plugin's default export to server/plugins.ts and client/plugins.ts, add apiKey() to server/config/auth.ts and apiKeyClient() to client/config/auth.ts, grant page:api-keys/access to the relevant roles, then run pnpm migrate to create the apikey table.

How do I call a NocoBase API with an API key?▼

Send the key in an x-api-key header, for example curl -H 'x-api-key: <key>' https://example.com/api/orders. Routes behind auth.required() or auth.optional() resolve the key into the owner's session, so no route changes are needed.

Why does my API key get a 401 response in Better Auth?▼

A 401 means the key is expired (KEY_EXPIRED) or unknown (KEY_NOT_FOUND), or enableSessionForAPIKeys is off so keys authenticate nothing. Disabling the owning user also rejects all of that user's keys immediately.

Can an API key have different permissions than its owner?▼

No. A key is exactly the user who created it and carries that user's roles; there is no per-key permission scoping. Clients may only set name, expiresIn, prefix, and metadata when creating a key.

What happens if an API key is leaked?▼

Revoking the leaked key is not enough because a key can mint successor keys with their own expiry. Review and revoke the owner's entire key list, since nothing links successor keys back to the one that created them.