Skip to content

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.

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.

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

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

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.

GET /api/v1/auth/me returns who the request is authenticated as. It works for any credential.

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

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.

POST /api/v1/auth/login

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

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.

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:

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

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:

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

passkey-sign-in.ts
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.

POST /api/v1/auth/refresh exchanges a refresh token for a new pair.

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

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

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