upAPI Docs

Authentication

API keys, what they scope to, and how they are stored.

Last updated

View as Markdown

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_HERE

A 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: true response header, and a top-level test_mode: true field 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.post returns a 1×1 PNG and html-to-pdf.post a one-page PDF. With output: "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 organization20
New keys per hour10
Times a key is displayed1, 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

SituationStatusCode
No x-api-key header401UNAUTHORIZED
Unknown or deleted key401UNAUTHORIZED
Key is valid, action is not allowed on your plan403FORBIDDEN
Our auth infrastructure is down503SERVICE_UNAVAILABLE
A stored platform session was rejected401AUTH_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.