Authentication
Every Plenary API request needs a credential. A site or integration uses an API key; a person (in the console, or through the CLI) uses a user session, a short-lived access token renewed with a refresh token. This page covers both at the level you need to call the API. For what each credential may do once authenticated, see Permissions.
Credentials at a glance
Section titled “Credentials at a glance”| Credential | Looks like | Send it as | Use it for |
|---|---|---|---|
| Public API key | pln_pub_… |
X-API-KEY header |
Reading published content and submitting forms from a site, app, or browser. |
| Private API key | pln_prv_… |
X-API-KEY header |
Server-side integrations: preview builds, imports, automation. Never ship it to a browser. |
| User access token | A JWT | Authorization: Bearer <token> |
Acting as a signed-in person. Lasts 15 minutes by default. |
| Refresh token | plr_rt_… |
JSON body of /api/v1/auth/refresh |
Getting a new access token. Lasts 30 days by default. |
Create and manage API keys in the console under Access Management → API Keys. See API keys for the console steps.
Send an API key
Section titled “Send an API key”Put the key in the X-API-KEY header:
curl -s "https://your-instance.plenarycms.io/api/v1/content/post?site_key=default&locale=en-us" \ -H "X-API-KEY: $PLENARY_API_KEY"import { createClient } from "@plenary/client";
// The client sends apiKey as the X-API-KEY header on every request.export const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL!, apiKey: process.env.PLENARY_API_KEY!, siteKey: process.env.PLENARY_SITE_KEY ?? "default", locale: process.env.PLENARY_LOCALE ?? "en-us",});The server also accepts the key as an api_key query parameter, for places that cannot set headers. The header wins when both are present. Query strings end up in logs and browser history, so prefer the header.
A value in X-API-KEY that does not start with pln_pub_ or pln_prv_ is not treated as a key at all, which also gives 401 authentication_required.
Public and private keys
Section titled “Public and private keys”Public key (pln_pub_…) |
Private key (pln_prv_…) |
|
|---|---|---|
| Access comes from | A fixed rule: read published content on the key’s site | The key’s own grants, like a role’s |
| Can hold grants | No | Yes, content:* capabilities only |
| Scoped by | The one Site chosen on the key | The key’s site, if it has one, and the model filters on its grants |
| Reads drafts | Only with Include draft content turned on | With content:entries:read |
| Sees private models and private fields | No | Yes, with content:entries:read |
| Writes | Form submissions only | Whatever its grants allow within content:* |
| Safe in a browser or mobile app | Yes | No |
| Value shown again after creation | Yes, from the key’s panel in the console | No, shown once; only a hash is stored |
A public key reaches the content read endpoints, the public form definition and form submission endpoints, and GET /api/v1/media/{media_id} for public assets. Every other endpoint returns 403 permission_denied. Its exact read rules are in Content API: public key restrictions.
A private key carries allow-only grants from the content: domain (entries, models, media, forms, form entries, webhooks, transformers, revisions). An admin:* grant is refused when the key is saved, with 422 api_key_grant_not_allowed. Instance administration (users, roles, keys, settings) is done by people, not keys. See Permissions for the capability list.
Use a public key for anything that renders content. Use a private key on a server when you need drafts, private fields, or writes, and keep it out of client bundles. In Next.js, a variable without the NEXT_PUBLIC_ prefix stays on the server.
Per-key restrictions
Section titled “Per-key restrictions”Every key can carry these optional restrictions. They are checked during authentication, before the request reaches any endpoint.
| Setting (console label) | Effect | Refusal |
|---|---|---|
| Expiry | The key stops working after this date. Public keys default to no expiry. | 401 api_key_invalid |
| Allowed origins | Only browser requests whose Origin matches may use the key. Entries are scheme://host[:port]; https://*.example.com admits every subdomain. Empty means any origin. |
403 api_key_origin_not_allowed |
| Rate limit (requests per minute) | Requests over the limit in a rolling minute are refused. Empty means unlimited. | 429 rate_limited |
| Include draft content | Public keys only: also read unpublished entries, for preview builds. | Not applicable |
Allowed origins only constrain browsers. Server-to-server requests send no Origin header and are never refused on origin grounds, so protect a server key by keeping it secret and limiting its grants.
Revoking a key in the console stops it immediately; requests with it then fail with 401 api_key_invalid.
Identify the current credential
Section titled “Identify the current credential”GET /api/v1/auth/me returns who the request is authenticated as. It works for any credential.
curl -s "https://your-instance.plenarycms.io/api/v1/auth/me" -H "X-API-KEY: $PLENARY_API_KEY"{ "principal": "api_key", "key_id": "baa0bb46-45b8-4c13-96e6-b01d4b6b4b56", "key_type": "public", "name": "Website", "grants": [], "site_key": "default"}For a private key, grants lists the key’s grants (each with "source": "key"); site_key is "" for an instance-wide key. For a user, principal is "user" and the body carries user_id, role, role_name, the resolved grants (each with "source": "role" or "user"), the sites the user can work in, and sms_enabled.
User sessions
Section titled “User sessions”People authenticate with a username or email and a password, optionally followed by a one-time code; with a passkey; or through the instance’s single sign-on provider. The result is the same token pair every way:
- An access token: a signed JWT, sent as
Authorization: Bearer <access_token>. It expires after 15 minutes by default. - A refresh token: an opaque
plr_rt_…string that mints new pairs. It expires after 30 days by default and is rotated on every use.
Most integrations never need a user session; use an API key instead. User sessions matter when you build a tool that acts as a specific person. The plenary CLI uses one and stores only the refresh token. See CLI.
All /api/v1/auth/* endpoints below are unauthenticated: they issue or revoke credentials rather than consume them. Bodies are JSON.
Sign in
Section titled “Sign in”POST /api/v1/auth/login
curl -s -X POST "https://your-instance.plenarycms.io/api/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{"identifier": "jane@example.com", "password": "correct-horse-battery"}'| Field | Description |
|---|---|
identifier |
Email address or username, matched case-insensitively. |
password |
The password. |
Without two-factor authentication the response is the token pair:
{ "status": "success", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "refresh_token": "plr_rt_Z9AcC…"}Two-factor sign-in
Section titled “Two-factor sign-in”When the user has two-factor authentication turned on, login returns a challenge instead of tokens. status tells you what happened:
status |
Meaning | Next step |
|---|---|---|
otp_sent |
Only one delivery method is available, and a code was sent to it. | Ask for the code, then call /auth/login/otp/verify. |
otp_required |
Several methods are available. | Let the user choose, call /auth/login/otp/send, then /auth/login/otp/verify. |
{ "status": "otp_required", "challenge_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "otp_methods": { "email": "j***@example.com", "sms": "+1 *** *** 7890" }}The otp_methods values are masked. sms is offered only when an SMS provider is configured. The challenge expires after 10 minutes.
POST /api/v1/auth/login/otp/send with {"challenge_id": "…", "otp_method": "email"} (or "sms") sends a code and answers {"status": "otp_sent", "otp_method": "email"}. Call it again to resend.
Text-message codes are budgeted per account: one a minute and five an hour, across every sign-in and challenge. A refused send answers 429 with otp_sms_cooldown or otp_sms_throttled and vars.retry_after, the seconds to wait (also in the Retry-After header); show it as a countdown and keep the resend control disabled until it reaches zero. When SMS is the only method and the budget is spent, login answers otp_required instead of otp_sent and sends nothing. An administrator can reset the budget from User Management. Email codes are not budgeted.
POST /api/v1/auth/login/otp/verify with {"challenge_id": "…", "otp_code": "482910"} completes sign-in and returns the same token pair as a direct login. Codes are 6 digits and expire 10 minutes after they are sent. Too many wrong codes lock the challenge; start a new login.
Single sign-on
Section titled “Single sign-on”A licensed instance can sign people in through one OpenID Connect or SAML 2.0 identity provider. The browser leaves for the provider from GET /api/v1/auth/sso/{key}/start (key is oidc or saml), comes back to Plenary’s callback, and is redirected to the console with a one-time login code. The console exchanges the code for the ordinary token pair:
curl -s -X POST "https://your-instance.plenarycms.io/api/v1/auth/sso/exchange" \ -H "Content-Type: application/json" \ -d '{"code": "plsc_…"}'The response is the same {"status": "success", "access_token": …, "refresh_token": …} as a password sign-in. The code lasts 60 seconds, works once, and only from the IP address that received it. No two-factor code is asked for: the identity provider handles its own. GET /api/v1/auth/sso/providers (unauthenticated) says whether a provider is enabled and whether single sign-on is required; when it is, a password sign-in by anyone but a super user is refused with 403 sso_required. The full flow, the settings, and every provider’s setup are on Single sign-on.
Passkeys
Section titled “Passkeys”A person who has enrolled a passkey (Touch ID, Face ID, Windows Hello, a security key, or a passkey synced by a password manager) can sign in with it alone: no identifier, no password, and no one-time code, because the authenticator’s own unlock is the second factor. Passkeys are available on every plan and on Plenary Cloud, and there is no setting that turns them off. People enrol them for themselves in Account Settings → Passkeys; see Users & Permissions.
A passkey sign-in is two calls around the browser’s WebAuthn prompt. First, fetch the challenge:
curl -s -X POST "https://your-instance.plenarycms.io/api/v1/auth/passkey/options" \ -H "Content-Type: application/json" \ -d '{}'{ "session_id": "4e6b3c1a-9d2f-4c7e-8a1b-2f3e4d5c6b7a", "options": { "challenge": "qK3…", "timeout": 300000, "rpId": "your-instance.plenarycms.io", "userVerification": "required" }}options is a standard PublicKeyCredentialRequestOptions in JSON form. Hand it to the browser, then post what comes back together with the session_id:
import { startAuthentication } from '@simplewebauthn/browser'
const base = 'https://your-instance.plenarycms.io/api/v1'
const { session_id, options } = await fetch(`${base}/auth/passkey/options`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}',}).then((r) => r.json())
// Opens the browser's passkey prompt. Throws if the person dismisses it.const credential = await startAuthentication({ optionsJSON: options })
const tokens = await fetch(`${base}/auth/passkey/verify`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ session_id, credential }),}).then((r) => r.json())// { status: "success", access_token: "…", refresh_token: "…" }POST /api/v1/auth/passkey/verify takes {"session_id": "…", "credential": {…}}, where credential is the PublicKeyCredential the browser produced, serialised with toJSON() (which is what startAuthentication returns). The response is the same token pair as a password sign-in, and never a two-factor challenge.
The session_id is valid for 5 minutes and for one attempt: a failed verify spends it, so start again from options. Every verification failure answers 401 passkey_invalid without saying why. When the instance requires single sign-on, a passkey sign-in by anyone but a super user is refused with 403 sso_required, like a password sign-in.
Passkeys are bound to the instance’s public address: a passkey enrolled at https://your-instance.plenarycms.io works only from pages on that origin. An instance whose configuration has no server.public_url cannot offer them and answers 400 passkey_unsupported on every passkey route.
Refresh
Section titled “Refresh”POST /api/v1/auth/refresh exchanges a refresh token for a new pair.
curl -s -X POST "https://your-instance.plenarycms.io/api/v1/auth/refresh" \ -H "Content-Type: application/json" \ -d '{"refresh_token": "plr_rt_Z9AcC…"}'{ "status": "success", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "refresh_token": "plr_rt_hQ41x…"}The refresh token you sent is revoked and a new one is returned. Store the new one immediately. If a refresh token that was already used is presented again, Plenary treats it as stolen: it revokes every token descended from the same sign-in, and the user must sign in again.
If several processes share one session, let only one of them refresh, or they will race and trip this protection.
Sign out
Section titled “Sign out”POST /api/v1/auth/logout with {"refresh_token": "…"} revokes the refresh token. It always answers {"status": "success"}, even for an unknown or already revoked token. Discard the access token on the client too.
Token lifetimes
Section titled “Token lifetimes”| Token | Default lifetime | Configuration key |
|---|---|---|
| Access token | 15 minutes | auth.jwt.access_token_ttl |
| Refresh token | 30 days | auth.jwt.refresh_token_ttl |
| Sign-in challenge | 10 minutes | Fixed |
| One-time code | 10 minutes | Fixed |
| Passkey challenge | 5 minutes | Fixed |
The lifetimes are set in the instance’s configuration file on self-hosted installs. See Self-hosted install.
An access token’s claims include sub (the user ID), exp, and an x-plenary-claims object with a profile snapshot for display. Do not use the claims for authorization decisions: permissions are checked on the server on every request, and a role change takes effect on the user’s next request.
Sign-in rate limits
Section titled “Sign-in rate limits”Counting happens before the password is checked, so a failed attempt costs the same as a successful one.
| Endpoint | Limit |
|---|---|
/auth/login |
20 per IP per 15 minutes, and 10 per identifier per 15 minutes |
/auth/login/otp/send |
3 per challenge per hour, 5 per user per 10 minutes, 5 per destination per 10 minutes; text messages also 1 per account per minute and 5 per account per hour |
/auth/refresh |
60 per IP per 15 minutes |
/auth/passkey/options, /auth/passkey/verify |
20 per IP per 15 minutes, each |
/auth/sso/{key}/start, the OIDC callback, the SAML ACS |
60 per IP per 15 minutes, shared |
/auth/sso/exchange |
60 per IP per 15 minutes |
An instance running with dev_mode: true turns these limits off, except the per-account text-message budget, which is stored with the account and also survives a restart.
Errors
Section titled “Errors”Errors use the standard envelope, { "error": { "code": "…" } }.
On any authenticated endpoint:
| Status | Code | Cause |
|---|---|---|
401 |
authentication_required |
No credential; an X-API-KEY value that is not a Plenary key; an API key sent as Authorization: Bearer; or the user’s account no longer exists or is inactive. |
401 |
api_key_invalid |
The API key is unknown, inactive, revoked, or expired. |
401 |
token_invalid |
The access token is malformed, has a bad signature, or has expired. Refresh and retry. |
403 |
api_key_origin_not_allowed |
The browser Origin is not in the key’s allowed origins. |
403 |
permission_denied |
Authenticated, but this credential may not do this. A public key gets this on every endpoint outside its fixed access. |
429 |
rate_limited |
The key’s per-minute limit is used up. |
On the sign-in endpoints:
| Status | Code | Endpoint | Cause |
|---|---|---|---|
400 |
invalid_request |
login, otp/verify | Missing or malformed body fields. |
401 |
invalid_credentials |
login | Unknown user, wrong password, or inactive account. |
403 |
sso_required |
login | Single sign-on is required and the identifier is not a super user’s. Sign in through the identity provider. |
429 |
rate_limited |
login, refresh, passkey/* | Rate limit exceeded. |
400 |
otp_method_required |
otp/send | Missing challenge_id or otp_method. |
400 |
otp_method_invalid |
otp/send | otp_method is not email or sms. |
400 |
otp_challenge_invalid |
otp/send, otp/verify | challenge_id is not a valid UUID. |
400 |
otp_email_unavailable |
otp/send | The user has no verified email address. |
400 |
otp_sms_unavailable |
otp/send | The user has no verified phone number, or SMS is not configured. |
400 |
otp_not_sent |
otp/verify | No code has been sent for this challenge yet. |
401 |
otp_session_expired |
otp/send, otp/verify | Challenge not found, or the account became inactive. |
401 |
otp_challenge_expired |
otp/send, otp/verify | Challenge expired, already used, or cancelled. |
401 |
otp_challenge_locked |
otp/send, otp/verify | Too many wrong codes. Start a new login. |
401 |
otp_expired |
otp/verify | The code expired. Send a new one. |
401 |
otp_invalid |
otp/verify | Wrong code. |
429 |
otp_rate_limited |
otp/send | Send limit exceeded. |
429 |
otp_sms_cooldown |
otp/send | A text message went out less than a minute ago. vars.retry_after is the seconds to wait. |
429 |
otp_sms_throttled |
otp/send | Five text messages in the last hour. vars.retry_after is the seconds to wait; an administrator can reset it. |
500 |
otp_send_failed |
otp/send | The email or SMS could not be delivered. |
400 |
passkey_unsupported |
passkey/* | The instance has no server.public_url to bind passkeys to. |
400 |
passkey_session_invalid |
passkey/verify | Missing session_id or credential, or a session that is unknown, older than 5 minutes, or already spent. Start again from options. |
401 |
passkey_invalid |
passkey/verify | The passkey could not be verified, or the account is inactive. The response does not say which. |
403 |
sso_required |
passkey/verify | Single sign-on is required and the account is not a super user’s. |
400 |
refresh_token_required |
refresh, logout | Missing refresh_token. |
401 |
refresh_token_invalid |
refresh | Unknown refresh token. |
401 |
session_revoked |
refresh | The token was already used or revoked. The whole session is now revoked. |
401 |
session_expired |
refresh | The refresh token has expired. Sign in again. |
401 |
sso_code_invalid |
sso/exchange | The login code is unknown, used, expired, or from another IP address. |
401 |
sso_user_inactive |
sso/exchange | The account was deactivated after the provider callback. |
403 |
license_feature_sso |
sso/* | Single sign-on is not included in the Free plan. |
404 |
sso_provider_not_found, sso_provider_disabled |
sso/{key}/start | No such provider, or the connection is switched off. |
The SDK throws PlenaryForbiddenError for 403 and PlenaryError for 401 and 429, each with status and code.
Related
Section titled “Related”- API keys: creating, restricting, and revoking keys in the console.
- Permissions: capabilities and grants.
- Single sign-on: OpenID Connect and SAML sign-in.
- Content API: what a key can read.
- Errors: every error code.