Authentication
API keys, what they scope to, and how they are stored.
Last updated
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.
Test-mode keys
Pick Test when you create a key (or pass mode: "test" to create_api_key) to get a
key that starts with upapi_test_. Use it while you wire up a no-code builder or write
integration tests:
- Every operation answers with a fixed sample built from that operation's documented response schema, so you get the real shape without real data.
- Samples are flagged twice: the
x-upapi-test-mode: trueresponse header, and a top-leveltest_mode: truefield in the body. - A test call never spends units, never reaches the upstream service and does not show
up as usage. It still needs a valid key, still checks required fields, malformed
JSON and proxy URLs (
400), and is still rate-limited per minute. - The same input always returns the same sample.
screenshot.postreturns a 1×1 PNG andhtml-to-pdf.posta one-page PDF. Withoutput: "url"you get a link to a static copy of that file. - A test key cannot use account tools (keys, billing, members). Switch to a live key for real results; nothing else in your calls has to change.
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 by an organization admin: ask your agent to run
create_api_key or revoke_api_key, or use the
API keys page. Both manage the same keys.
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.
Connected platform accounts
Some operations act as a signed-in account on another platform (TikTok, Instagram, LinkedIn, X,
Reddit, Facebook). They take that account's session as an input: sessionCookies, or
auth_token and ct0 for X. When your workspace has a connected account for the platform, you
can leave that input out and the gateway fills it from the stored session. This is for MCP sign-in
and the dashboard only for now: an API key must still send the session itself. A stored session
the platform rejects answers 401 AUTH_EXPIRED with a reconnect hint and is not charged.
How to connect an account, and every rule for using it, is on
Connect platform accounts.
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 |
| A stored platform session was rejected | 401 | AUTH_EXPIRED |
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.