API authentication

All platform operations—agents, functions, serverless workloads, secrets, Pub/Sub, vector indexes, and Gateway configurations—are served over a unified HTTPS endpoint at https://api.codyhill.dev.

Authentication header

Authenticated requests pass a bearer token in the HTTP Authorization request header:

Authorization: Bearer <token-or-key>

---

Supported credential types

Credential Type	Format / Prefix	Lifetime	Primary Purpose
API Keys	cai_<keyid>_<secret>	1–3,650 days (or no expiry)	Automated scripts, CI/CD pipelines, background services.
Session Tokens	Signed Session String	12 hours	Interactive CLI sessions (platformctl login) & Console UI.
Workload Keys	cai_wl_<keyid>_<secret>	Bound to workload deployment	Injected into a deployed workload so it can mint a short-lived, read-only token for its own project's secrets (the call-time secret() read).
Anonymous	None	—	Public health endpoints (/healthz) and unauthenticated agent invocations.

A workload key is not a small API key — it holds no project authority at all. It is refused on both the resource and metadata axes, for its own project as much as any other, before any grant is read, so every project route answers 404 not found rather than 403. Its single capability is the token mint at POST /v1/projects/{projectID}/secrets:issue-token, and only when the key's project matches the project in the path.

Bound environment values do not travel over this key either. Applying a binding writes the value into the workload's own platform-managed secret storage and rolls a new version; by the time the process reads the variable, no credential is involved.

---

1. Interactive session tokens

Authenticate via CLI or API to acquire a 12-hour signed session token.

platformctl

platformctl login

The CLI caches the session token locally for 12 hours.

curl

curl -sX POST "https://api.codyhill.dev/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your-password"}'

Expected response:

{
  "token": "eyJhbGciOi...",
  "email": "user@example.com",
  "expires_at": 1765480000
}

---

2. API Key authentication

API keys pass in the same Authorization: Bearer header:

curl -s "https://api.codyhill.dev/v1/agents?project=$CAI_PROJECT" \
  -H "Authorization: Bearer cai_7f3a9c_9V2V3PFuKq7ZmT4xN1sJdR6cB0wYhLgA"

---

Real-time permission evaluation

Permissions are evaluated dynamically on every API request:

• Roles, project memberships, and organization privileges are re-read live from the database.
• Demotions or privilege revocations take effect immediately on subsequent API calls.
• Stale session tokens or API keys cannot perform actions after an account's underlying permissions have been demoted or revoked.

---

Rate limiting and request tracking

• Rate Limits: Requests are subject to rate limiting counted per credential (or per IP address for unauthenticated calls). Exceeding limits returns HTTP 429 Too Many Requests with a Retry-After header.
• Request IDs: All responses include an X-Request-Id header for audit tracing and troubleshooting.

{
  "error": "rate limit exceeded",
  "request_id": "req_9f8a7b6c5d"
}