Canonical

API keys

Self-service key registration, rotation, and usage inspection.

Updated 2026-04-21

API keys are SHA-256 hashed at rest. The raw value is shown exactly once at creation or rotation — store it securely.

POST /api/keys/register

Public self-service registration for a free-tier key. No auth required. Rate limited per IP (3 requests per hour).

Field	Type	Required	Description
`projectName`	string	yes	1–100 chars. Must be unique among active keys.
`email`	string	yes	Valid email, ≤320 chars. Receives the setup link.
`description`	string	no	≤500 chars.
`website`	string	no	Honeypot. Leave empty. Bots that fill this get a fake `{ success: true }` and no key.

Free-tier ceiling: 20 req/min, 500/day, 5000/month, maxPageSize 20, canPush false, search requires a filter.

curl -X POST https://orakel.cloud/api/keys/register \
  -H "Content-Type: application/json" \
  -d '{"projectName":"my-app","email":"me@example.com"}'

Response (status 201):

{
  "raw": "orakel_…",
  "keyPrefix": "orakel_abc",
  "projectName": "my-app",
  "tier": "free",
  "setupUrl": "https://orakel.cloud/setup?key=orakel_…",
  "limits": { "rateLimitPerMinute": 20, "dailyLimit": 500, "monthlyLimit": 5000, "maxPageSize": 20 }
}

POST /api/keys/rotate

Requires a valid bearer token. Deactivates the current key and creates a replacement with the same tier and limits. Returns the new raw value exactly once.

curl -X POST https://orakel.cloud/api/keys/rotate \
  -H "Authorization: Bearer $ORAKEL_KEY"

Response (status 201): { raw, keyPrefix, projectName, tier, rotatedFrom }.

GET /api/keys/usage

Self-inspection. Returns the caller's tier, limits, current usage, and reset timestamps.

curl -H "Authorization: Bearer $ORAKEL_KEY" \
  https://orakel.cloud/api/keys/usage

Response:

{
  "projectName": "my-app",
  "tier": "free",
  "limits": { "rateLimitPerMinute": 20, "dailyLimit": 500, "monthlyLimit": 5000, "maxPageSize": 20, "canPush": false, "requireFilterOnSearch": true },
  "usage": { "today": 42, "thisMonth": 180, "total": 2400, "dailyRemaining": 458, "monthlyRemaining": 4820 },
  "resets": { "daily": "2026-04-21T00:00:00Z", "monthly": "2026-05-01T00:00:00Z" }
}

Quotas reset at UTC midnight (daily) and at the first of the month (monthly).

Error modes

Status	Meaning	Action
400	Invalid JSON or schema violation on register	Inspect `details[]`
401	Missing or invalid API key on rotate/usage	Check the `Authorization` header
404	Rotate called for a key that no longer exists	Register a new key
409	`projectName` already taken on register	Choose a unique name
429	Register: IP rate limit (3/hour). Rotate/usage: per-key RPM or quota	Back off

Rate limits

/api/keys/register — 3 requests per IP per hour (shared with the access-request form).
/api/keys/rotate and /api/keys/usage — per-key RPM per tier.

Typical use cases

Onboarding: call register from a product signup flow.
Key hygiene: rotate quarterly or on suspected compromise.
Client-side usage badges: call usage and render remaining quota.