Authentication
API keys, what they scope to, and how they are stored.
Every machine call carries an API key in the x-api-key header. There is no
OAuth flow, no bearer token and no signature to compute for the REST gateway.
curl -X POST https://api.upapi.io/github-trending.get \
-H 'x-api-key: upapi_YOUR_KEY' \
-H 'content-type: application/json' \
-d '{}'The same header authenticates the usage endpoint and the local MCP server.
Key format
A key is the prefix upapi_ followed by 48 hexadecimal characters — 54
characters in total.
upapi_YOUR_KEY_HEREA real key has 48 hex characters after the prefix; the placeholder above is not one. The first 12 characters are kept in plain text so the dashboard can label a key in a list. Everything else exists only as a SHA-256 hash. A presented key is hashed and matched against that hash, which is why a lost key cannot be recovered — only replaced.
Keys belong to the organization
A key is scoped to the organization that created it, not to the person. Two consequences worth designing around:
- Every member with admin rights sees and manages the same set of keys, and a key keeps working when its creator leaves.
- Usage and quota are pooled across all of an organization's keys. Ten keys do not give you ten quotas — see Rate limits.
Keys carry no per-operation scoping today. A key can call every operation published to your organization.
Limits
| Keys per organization | 20 |
| New keys per hour | 10 |
| Times a key is displayed | 1, at creation |
Managing keys
Keys are created and deleted from Dashboard → API keys, by an organization admin.
There is no key-management REST API
Creating, listing and deleting keys happen through the dashboard only. If you are building provisioning automation, that is not available yet — do not plan around an endpoint that does not exist.
Deleting a key removes it outright rather than flagging it as revoked. Calls
presenting a deleted key fail immediately with UNAUTHORIZED.
Failure modes
| Situation | Status | Code |
|---|---|---|
No x-api-key header | 401 | UNAUTHORIZED |
| Unknown or deleted key | 401 | UNAUTHORIZED |
| Key is valid, action is not allowed on your plan | 403 | FORBIDDEN |
| Our auth infrastructure is down | 503 | SERVICE_UNAVAILABLE |
503 is not a credential problem
A 503 here means we could not check your key, not that your key is bad. Retry rather than rotating
credentials — see Errors. Key-authenticated callers get SERVICE_UNAVAILABLE;
AUTH_UNAVAILABLE is the same outage seen from a session surface such as the dashboard or the
hosted MCP endpoint.