UpHeron
View as Markdown

Authentication

Every API request needs a workspace API token. A token acts for its workspace: it sees and changes that workspace's monitors and spends that workspace's credit.

Create a token

  1. Sign in and open Settings → API tokens.
  2. Name the token after what will use it, for example deploy-bot or claude-agent.
  3. Choose its scope and, optionally, an expiry date.
  4. Copy the token. It starts with pgk_ and is shown only once; UpHeron stores only a hash of it.

You can have up to 50 active tokens per workspace. Revoke a token in the same place; it stops working immediately.

Agents without a token: auth.md

An AI agent that supports auth.md does not need a token from you. It registers at https://upheron.com/agent/identity, you type the 6-digit code it shows you, and it receives access tokens starting with pga_ that last an hour and refresh themselves. They work exactly like API tokens with the read and write scopes. Settings → Connected agents lists these agents; disconnect one there. Agents read the details at /auth.md.

Scopes

Scope Allows
read Every GET: account, locations, monitors, results, incidents, payments, receipts
write Everything read allows, plus creating, changing, pausing and deleting monitors, acknowledging incidents, and paying

Give each agent the smallest scope it needs. An agent that only reports status should have a read token, which can never spend money.

Send the token

Send the token in the X-API-Key header:

curl https://upheron.com/api/v1/account -H "X-API-Key: pgk_…"

Authorization: Bearer pgk_… also works for requests that do not carry a payment.

Use X-API-Key for anything that can be paid. When an MPP client retries a paid request it puts its payment credential in the Authorization header (Authorization: Payment …), and a request can only have one Authorization header. X-API-Key keeps your token alongside it.

Errors

Status error Meaning
401 missing_api_key No token was sent
401 invalid_api_key The token is wrong or was revoked. An agent can get access itself with auth.md: the WWW-Authenticate header points to https://upheron.com/.well-known/oauth-protected-resource
401 token_expired The token passed its expiry date
403 insufficient_scope The request needs the write scope
429 rate_limited Too many requests or failed sign-ins; wait for Retry-After seconds

Repeated failed authentication from one IP address is rate limited, so tokens cannot be guessed.

Keep tokens safe

  • Store tokens in your agent's secret store or environment, never in code or prompts that are logged.
  • Use one token per agent or integration, so you can revoke one without breaking the others.
  • Set an expiry date on tokens for experiments.
  • Tokens are not tied to an IP address; anyone with the token can use it. Revoke a token you think has leaked.