API keys
Developer API keys enable programmatic access to PoQ by both developers and agents. Use them to access the PoQ Developer API (/developer/v1) and the PoQ MCP server (/mcp).
What they are
An API key is a bearer token with the prefix poq_live_. Each key is scoped to one user within one organization.
| Property | Detail |
|---|---|
| Format | poq_live_ + 32 base62 characters (41 chars total) |
| Header | Authorization: Bearer poq_live_... |
| Scope | One organization; projects and uploads created via the key live in that organization |
| Attribution | Work performed with a key is attributed to the user who created it |
Creating a key
Open API Keys in the app. Give the key a name and copy the token when it appears. It is shown exactly once and cannot be retrieved later. You can still list keys and see their prefix (poq_live_…).
Only originators of your current organization can create keys. If you are not an originator, ask an organization admin to grant access or create a key for you.
Managing keys
From the same API Keys page you can list active keys and revoke them by setting an expiry. Revoked keys stop working immediately.
Authorization layers
A valid key is necessary but not always sufficient.
| Endpoint class | Requirements |
|---|---|
GET /developer/v1/ping | Valid, non-expired key |
| Project and upload endpoints | Valid key and the key's creator must still be an originator within the organization |
The originator check runs on every project request, not just at creation time. If the creator loses originator status within the organization, existing keys remain valid for ping but can no longer create or manage projects.
Security
| Practice | Why |
|---|---|
| Store keys in a secrets manager | Plaintext keys grant full organization-scoped API access |
| Never commit keys to source control | Treat a leaked key like a leaked password |
| Set an expiry for short-lived automation | Limits blast radius if a key is exposed |
| Rotate after compromise | Revoke the old key in the app, create a new one |
Presigned upload URLs returned by upload-session endpoints are a separate credential. PUT requests to those URLs need no Authorization header.
What keys are not
| Not this | This instead |
|---|---|
| Web app access token | Wallet login at https://sapien-poq.up.railway.app, for browser use |
| Presigned upload URL | Returned per file during upload; scoped to one object and time-limited |
| Validator credentials | Validators use wallet auth on app routes, not API keys |
See also
| Page | Description |
|---|---|
| Quickstart - API | End-to-end workflow with a new key |
| Developer API - REST | HTTP endpoint reference |
| MCP server | Tool-based access with the same keys |