public-api-designlisted
Install: claude install-skill Canhada-Labs/ceo-orchestration
# Public API Design
## Fail-Fast Rule
If authentication fails, **return immediately** with a structured error.
Never leak internal error details, stack traces, or database schemas in
public API responses. Never serve stale or partial data without explicit
quality flags. API consumers make automated trading decisions — wrong
data is worse than no data.
## Cardinal Rule
**The public API is a product, not an endpoint.** It needs versioning,
documentation, rate limits, error contracts, deprecation policy, and
developer experience design — not just working routes. An undocumented
API with no error contract is a support ticket generator.
## Architecture: Admin Keys vs User Keys
{{PROJECT_NAME}} currently has `api-keys.ts` with admin-only key management.
The public API requires a second layer: **user self-service keys**.
```
┌─────────────────────────────────┐
│ API Key Types │
├───────────────────────────���─────┤
│ │
│ Admin Keys (existing) │
│ ├── Managed via /admin panel │
│ ├── Full access (read/write) │
│ ├── Created by the Owner only │
│ └── Stored in AdminConfig │
│ │
│ User Keys (new) │
│ ├── Self-service via /settings │
│ ├── Scoped by user's tier │
│ ├── Rate limited per tier │
│ ├── Stored in Supabase │
│ └── Tied to user_id via RLS │
│ │
└─────────────────────────────────