API Keys
An API key is the credential a site, app, script, or CI job uses to call the Plenary API. There are two types. A public key reads published content and submits forms, and is safe to ship to a browser. A private key carries its own grants for content work and must stay on a server. Every public key, and most private keys, belong to one site. Keys are for integrations; people sign in with their own user accounts instead.
Public and private keys
Section titled “Public and private keys”| Public key | Private key | |
|---|---|---|
| Secret prefix | pln_pub_ |
pln_prv_ |
| Safe in a browser | Yes | No. Server only. |
| What it can do | A fixed, read-only view: published entries, form definitions, form submission, single public media items | Exactly its grants, from content:* capabilities only |
| Site | Exactly one, required | One site, or none for an instance-wide key that only a super user may manage |
| Scoped by | Its site | Its grants, which can carry a model filter and are held to the key’s site |
| Grants | Never. Rejected with api_key_grants_not_allowed. |
Any content:* capability. admin:* is rejected with api_key_grant_not_allowed. |
| Sees private models and fields | No. A private model answers 404; private fields are left out. |
Yes, with content:entries:read |
| Reads drafts | Only with Include draft content, which also swaps a published entry’s pending changes in for its live content | Yes, with content:entries:read; pending changes arrive in draft beside the live content |
| Secret can be shown again | Yes, from the key’s panel | No. Shown once at creation. |
A public key can, on its site:
- read published entries of models not marked private (drafts too, if Include draft content is on);
- read a form definition with
GET /api/v1/forms/{form_key}; - submit form entries with
POST /api/v1/forms/{form_key}/entries; - read one of the site’s media items with
GET /api/v1/media/{media_id}, unless the asset is private.
Every other route refuses a public key with 403 permission_denied.
A private key can do exactly what its grants allow, and nothing under admin:*: it cannot manage users, roles, other keys, sites, or settings. On a site-bound key every grant reaches that site only, and a request that names no site uses the key’s site. Use one for server-side rendering that needs private fields, preview builds, content imports, and model sync in CI. The capability list is in the Permissions reference.
Create a key
Section titled “Create a key”- Pick the site in the console’s site switcher, go to Access Management → API Keys, and click New.
- Enter a Name. It appears in the key list and in revision history for anything the key changes.
- Choose the Type: Public or Private. You cannot change the type later.
- Check the Site. A public key needs one. A private key on a site has its grants held to that site; a super user can choose Instance-wide instead, for a key whose grants may name any site. For a private key, open the Grants tab and tick the capabilities it needs, with a model scope where useful.
- Optionally set Expiry, Allowed origins, and Rate limit (requests per minute). See Restrictions.
- Click Create key.
The console shows the secret in a Key created banner. Copy it now. A private key’s secret is shown once; Plenary stores only a hash of it. A public key’s secret stays recoverable from the key’s panel, because it is not a secret in the first place.
Creating keys needs admin:api_keys:create on the key’s site, which the Admin and Developer roles have. Those capabilities reach the site’s own keys only: a key manager on one site cannot see, create, or move keys on another. Instance-wide keys are a super user’s.
Create a key with the API
Section titled “Create a key with the API”POST /api/v1/api-keys with a user’s access token. API keys cannot create other keys.
curl -X POST https://your-instance.plenarycms.io/api/v1/api-keys \ -H "Authorization: Bearer $PLENARY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Marketing site (server)", "key_type": "private", "is_active": true, "expires_at": "2027-10-07T00:00:00Z", "site_key": "marketing", "grants": [ { "key": "content:entries:read" }, { "key": "content:media:read" } ] }'The response is the key’s detail plus key, the secret. This is the only response that contains a private key’s secret. The key’s grants come back with its site filled in. A grant that names another site is refused (422 api_key_grant_site_mismatch), and an unknown site is 422 api_key_site_not_found.
{ "id": "aab4bac0-2263-4393-8bab-0cce0ed22adf", "name": "Marketing site (server)", "description": null, "key_type": "private", "key_prefix": "pln_prv_", "is_active": true, "last_used_at": null, "expires_at": "2027-10-07T00:00:00Z", "created_at": "2026-10-07T09:16:16Z", "created_by": "Jane S.", "revoked_at": null, "revoked_by": null, "grants": [ { "key": "content:entries:read", "site_key": "marketing" }, { "key": "content:media:read", "site_key": "marketing" } ], "site_key": "marketing", "allowed_origins": [], "rate_limit_per_minute": 0, "include_drafts": false, "key": "pln_prv_8c1f…"}A public key takes a site_key and no grants:
{ "name": "Marketing site (browser)", "key_type": "public", "is_active": true, "site_key": "marketing", "allowed_origins": ["https://www.example.com", "https://*.vercel.app"]}Or use the CLI, which prints the secret alone on stdout so you can capture it. It needs a user session from plenary login:
KEY=$(npx plenary api-keys create --name "Marketing site (server)" --site marketing \ --grant content:entries:read --grant content:media:read)See the CLI reference.
Grants on private keys
Section titled “Grants on private keys”A private key’s grants work like a role’s: allow-only, unioned, and narrowed by optional filters. Give each key the least it needs. Typical sets:
| Use | Grants |
|---|---|
| Server-rendered site that needs private fields or drafts | content:entries:read, content:media:read |
Model sync in CI (plenary metadata push) |
content:models:read, content:models:create, content:models:update, content:forms:read, content:forms:create, content:forms:update, plus content:transformers:manage if models carry transformers |
| Content import script | content:entries:read, content:entries:create, content:entries:update, plus content:entries:publish if it publishes, and content:media:create for uploads |
| Form-entry export | content:form_entries:read with content_model_key set to the form’s key |
A key cannot hold a role. Each key carries its own list, so changing a role never silently changes what a deploy job can do.
Restrictions
Section titled “Restrictions”Both key types accept these optional restrictions. They are checked when the request authenticates, before any route runs.
| Console label | API field | Effect | Refusal |
|---|---|---|---|
| Expiry | expires_at (RFC 3339) |
The key stops working at this time. The console offers Never, 30 days, 90 days, and 1 year. | 401 api_key_invalid |
| Allowed origins | allowed_origins |
Browser origins that may use the key, as scheme://host[:port]. https://*.example.com allows every subdomain. Empty allows any origin. |
403 api_key_origin_not_allowed |
| Rate limit (requests per minute) | rate_limit_per_minute |
Requests per sliding minute. 0 means unlimited. |
429 rate_limited |
| Include draft content | include_drafts |
Public keys only. Lets the key read unpublished entries, and a published entry’s pending changes in place of its live content, for preview builds. | none |
Allowed origins constrain browsers only. The check reads the request’s Origin header, which server-to-server requests do not send, so a request without one is never refused on origin grounds. Restrict a server key with tight grants and an expiry instead.
Use a key
Section titled “Use a key”Send the key in the X-API-KEY header:
curl "https://your-instance.plenarycms.io/api/v1/content/blog_post?site_key=marketing&limit=10" \ -H "X-API-KEY: $PLENARY_API_KEY"The server also accepts the key as an api_key query parameter. Prefer the header: query strings end up in logs and browser history.
To check which key a request is using, call GET /api/v1/auth/me with it:
{ "principal": "api_key", "key_id": "aab4bac0-2263-4393-8bab-0cce0ed22adf", "key_type": "private", "name": "Marketing site (server)", "grants": [{ "key": "content:entries:read", "site_key": "marketing", "source": "key" }], "site_key": "marketing"}Where each key belongs in a web app
Section titled “Where each key belongs in a web app”Put a private key only in server-side environment variables: a Next.js server component, route handler, or server action; a build step; a CI secret. Never give it a NEXT_PUBLIC_ prefix or any other prefix your framework uses to expose variables to the browser.
A public key may appear in browser code, because it can only read what your site already shows the world. Still restrict it with Allowed origins so other sites cannot borrow your quota.
# Server only. Never exposed to the browser.PLENARY_BASE_URL=https://your-instance.plenarycms.ioPLENARY_SITE_KEY=marketingPLENARY_API_KEY=pln_prv_your_private_key
# Safe in the browser: a public key restricted to your origins.NEXT_PUBLIC_PLENARY_PUBLIC_KEY=pln_pub_your_public_keyimport { createClient } from "@plenary/client";
// Used only from server code: server components, route handlers, build scripts.export const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL!, siteKey: process.env.PLENARY_SITE_KEY!, apiKey: process.env.PLENARY_API_KEY!, locale: "en-us",});If you render everything on the server, you need no public key at all. Use a public key when browser code calls Plenary directly, for example a client-side search box or a form that posts straight to submitForm. See the client SDK.
Deactivate, revoke, and delete
Section titled “Deactivate, revoke, and delete”| Action | Console | Effect |
|---|---|---|
| Deactivate | Turn off Active on the key | The key is refused (401 api_key_invalid) until you turn it back on. Use it to pause access. |
| Revoke | Revoke | The key stops working immediately. Its record stays, showing who revoked it and when. |
| Delete | Delete key | The key and its record are removed. Anything still using it gets 401. |
A key cannot delete itself (403 api_key_delete_self).
Through the API, revoke a key by sending revoked_at on PUT /api/v1/api-keys/{id}. PUT replaces the key’s editable fields, so send the full set (name, description, is_active, expires_at, revoked_at, grants, site_key, and the restrictions) every time. A field you leave out is cleared: a private key sent without site_key becomes instance-wide, which only a super user may do, and a public key without one is refused.
Rotate a key
Section titled “Rotate a key”Plenary does not rotate keys in place. To replace a key with no downtime:
- Create a new key with the same type, site, grants, and restrictions.
- Deploy the new secret to every place that uses the old one.
- Confirm traffic has moved, then revoke the old key.
Rotate on a schedule by giving private keys an Expiry and replacing them before it passes. Public keys default to no expiry; revoke and replace one if it is abused.
Last used
Section titled “Last used”The key list and detail include last_used_at, shown in the console as “last used” or “never used”.
Related
Section titled “Related”- Permissions reference: every capability a private key can hold.
- Users & Permissions: access for people.
- Live Preview: preview builds that read drafts.
- Errors: authentication error codes.