Authentication
Public reads need no auth. You only need a key to read drafts and private content, or to write (create, update, delete posts) and manage webhooks.
Keys are flg_ tokens, hashed at rest, scoped, revocable, and not expiring. Up to 5 per account.
Creating a key
- Open your Floggy dashboard.
- Go to Settings -> Developer.
- Create a key, pick its scopes (or a preset), and copy it.
The full key (flg_ followed by 32 characters) is shown once at creation. Floggy stores only a hash, so it cannot show you the key again. If you lose it, revoke and create a new one.
Using a key
Keys are created in the Dashboard (Settings -> Developer) and used by the SDK and CLI automatically. With the SDK, pass it as key:
import { createClient } from "@floggy/cms";
const floggy = createClient({
project: "projecta",
key: process.env.FLOGGY_API_KEY, // only needed for drafts / private content
});Scopes
A request succeeds when the key carries every scope the endpoint requires. The * scope satisfies all of them. A scoped key that is missing a required scope returns 403 {"error":"Insufficient scope","required":[...]}.
| Scope | Grants |
|---|---|
posts:read |
Read your own posts, including drafts and private posts. |
posts:write |
Create and update posts, bulk publish/unpublish. |
posts:delete |
Delete posts (and bulk delete). |
uploads:write |
Upload media. |
notes:read |
Read notes. |
notes:write |
Create and update notes. |
tasks:read |
Read tasks. |
tasks:write |
Create and update tasks. |
profile:read |
Read profile / account settings. |
profile:write |
Update profile / account settings. |
analytics:read |
Read analytics. |
newsletter:read |
Read newsletter subscribers and data. |
newsletter:write |
Manage newsletter subscribers and sends. |
webhooks:read |
List webhook endpoints. |
webhooks:write |
Create, update, delete webhook endpoints. |
* |
Full access to everything above. Trusted automation only. |
Presets
The create-key UI offers three presets so you do not have to hand-pick scopes:
| Preset | Scopes | Use it for |
|---|---|---|
| Read-only | all *:read (posts:read, notes:read, tasks:read, profile:read, analytics:read, newsletter:read, webhooks:read) |
Anything a frontend touches. Safe to expose. |
| Editor | Read-only plus posts:write, posts:delete, uploads:write |
CMS authoring tools, CI that publishes posts. |
| Full access | * |
Your own trusted CLI and agents only. Never in a frontend. |
For a blog frontend that only consumes published content you usually need no key at all. Add a Read-only key only if the frontend must also fetch drafts or private posts (for example a preview build).
Key safety and disclosure
The keys that leak in practice are the ones embedded in frontends. Minimize the blast radius before that happens.
- Never commit keys. Keep them out of git, source, and client bundles. Use a
.gitignored.env. - Use environment variables. The convention across Floggy tooling is
FLOGGY_API_KEY.export FLOGGY_API_KEY="flg_xxxxxxxx..." - Use a Read-only key for anything a browser can see. If a Read-only key leaks, the holder can read content that is already public anyway, plus your drafts and private posts. They cannot write, delete, or change settings.
- Never ship a Full-access (
*) or Editor key to a frontend. A leaked Editor key can publish and delete your posts. A leaked*key is a full account compromise. - Prefer server-side fetching. Call the API from your server (server components, route handlers, build steps) so the key never reaches the client. A purely public blog frontend can skip the key entirely.
- Rotate by revoke + recreate. There is no expiry and no in-place rotation. To rotate: create the new key, deploy it, then revoke the old one in Settings -> Developer.
- Audit usage. Each key records a
lastUsedAt. If a key shows unexpected activity, revoke it immediately.
What a leaked Read-only key can and cannot do
| Can | Cannot |
|---|---|
| Read your published posts (already public) | Create, edit, or delete posts |
| Read your drafts and private posts | Upload media |
| Read analytics, notes, tasks, profile, newsletter data (read scopes) | Change any account settings |
| List webhook endpoints | Manage webhooks, manage subscribers, or anything *:write |
This is why Read-only is the right default for exposed surfaces: the worst case is read access to content you mostly publish anyway. Keep write and delete power in keys that never leave your servers.