API Keys

Creating, managing, and securing project-scoped API keys.

API keys provide project-scoped access for fetching published widgets and delivering assets. They are designed for client-side use in mobile apps and web applications.

Key format

API keys follow the format pk_ followed by 32 hex characters:

pk_550e8400e29b41d4a716446655440000

The pk_ prefix stands for "project key" and makes keys easily identifiable.

Creating keys

POST/api/projects/{projectId}/api-keysJWT
Request body
{
"name": "Android App Key",
"permissions": "READ",
"expiresAt": "2026-12-31T23:59:59"
}
Response
{
"id": "770e8400-e29b-41d4-a716-446655440000",
"name": "Android App Key",
"key": "pk_550e8400e29b41d4a716446655440000",
"keyPrefix": "pk_550e84",
"permissions": "READ",
"createdAt": "2026-01-15T10:30:00"
}

Save your key immediately

The full API key is only returned once at creation time. It is hashed with SHA-256 before storage and cannot be retrieved later. If you lose the key, you must create a new one.

Permissions

| Permission | Allowed operations | |---|---| | READ | Fetch published widgets, deliver assets | | READ_WRITE | All READ operations plus resource modification |

Always use READ permissions for client-side keys (mobile apps, web frontends). Reserve READ_WRITE for trusted server-side integrations.

Using keys

Pass the API key via the X-API-Key header:

curl https://your-api.com/api/v1/widgets/hero-carousel \
-H "X-API-Key: pk_550e8400e29b41d4a716446655440000"

Or as a query parameter:

curl "https://your-api.com/api/v1/widgets/hero-carousel?api_key=pk_550e8400e29b41d4a716446655440000"

Listing keys

GET/api/projects/{projectId}/api-keysJWT

The list endpoint returns the key prefix only — never the full key:

Response
[
{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "name": "Android App Key",
  "keyPrefix": "pk_550e84",
  "permissions": "READ",
  "lastUsed": "2026-01-20T14:30:00",
  "expiresAt": "2026-12-31T23:59:59",
  "createdAt": "2026-01-15T10:30:00"
}
]

Revoking keys

DELETE/api/projects/{projectId}/api-keys/{keyId}JWT

Revoking a key immediately invalidates it. Any client using the revoked key will receive authentication errors.

Security details

  • Hashing — Keys are hashed with SHA-256 before storage. The database never contains plain-text keys.
  • Prefix storage — The first 8 characters of the key are stored as keyPrefix for identification in the dashboard.
  • Expiration — Keys can optionally have an expiresAt timestamp. Expired keys are automatically rejected.
  • Last used tracking — The lastUsed timestamp updates on each successful authentication, helping identify unused keys.
WidgetsInstallation