Skip to content

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 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.

  1. Pick the site in the console’s site switcher, go to Access Management → API Keys, and click New.
  2. Enter a Name. It appears in the key list and in revision history for anything the key changes.
  3. Choose the Type: Public or Private. You cannot change the type later.
  4. 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.
  5. Optionally set Expiry, Allowed origins, and Rate limit (requests per minute). See Restrictions.
  6. 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.

POST /api/v1/api-keys with a user’s access token. API keys cannot create other keys.

Terminal window
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:

Terminal window
KEY=$(npx plenary api-keys create --name "Marketing site (server)" --site marketing \
--grant content:entries:read --grant content:media:read)

See the CLI reference.

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.

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.

Send the key in the X-API-KEY header:

Terminal window
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"
}

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.

.env.local
# Server only. Never exposed to the browser.
PLENARY_BASE_URL=https://your-instance.plenarycms.io
PLENARY_SITE_KEY=marketing
PLENARY_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_key
lib/plenary.ts
import { 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.

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.

Plenary does not rotate keys in place. To replace a key with no downtime:

  1. Create a new key with the same type, site, grants, and restrictions.
  2. Deploy the new secret to every place that uses the old one.
  3. 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.

The key list and detail include last_used_at, shown in the console as “last used” or “never used”.