UpHeron
View as Markdown

Agent sign-up with auth.md

UpHeron supports auth.md, an open profile for agent registration. An AI agent that supports it gets API access by itself:

  • For its user. The agent knows its user's email (or its agent provider vouches for the user). The user opens a link, signs in and types a 6-digit code the agent shows them. The agent then works in the user's workspace.
  • On its own. The agent signs up anonymously and gets a pay-as-you-go agent workspace straight away, like an agent that pays without an account. Its user can claim it later: its monitors, history and credit move into the user's workspace.

Nobody copies an API token around, and the user can disconnect the agent at any time.

Agents read the instructions at /auth.md. Point an agent at it:

Get access to UpHeron by following https://upheron.com/auth.md, acting for me (my email is [email protected]).

How it works

  1. The agent finds the endpoints in the authorization server metadata, or from the WWW-Authenticate header of any 401 from the API.
  2. It registers at POST /agent/identity as service_auth (with the user's email), identity_assertion (with an ID-JAG from a trusted agent provider) or anonymous.
  3. To act for a person, it shows them a link and a 6-digit code. The person signs in, checks what the agent asks for and types the code. The agent waits by polling the token endpoint.
  4. The agent receives an identity assertion and exchanges it at POST /oauth2/token for access tokens that last an hour. The tokens start with pga_ and work like API tokens on the API and the MCP server, with the read and write scopes.
Endpoint Purpose
GET /.well-known/oauth-protected-resource Protected resource metadata (RFC 9728)
GET /.well-known/oauth-authorization-server Authorization server metadata (RFC 8414) with the agent_auth block
GET /auth.md Instructions for agents
POST /agent/identity Register
POST /agent/identity/claim Start or restart the code step
POST /oauth2/token Exchange an identity assertion (urn:ietf:params:oauth:grant-type:jwt-bearer) or poll the code step (urn:workos:agent-auth:grant-type:claim)
POST /oauth2/revoke Revoke an access token (RFC 7009)
POST /agent/event/notify Security events from trusted agent providers (RFC 8935)

What the user sees

The link opens Authorize an AI agent on UpHeron. The person signs in or creates an account, and the page says what the agent asks for:

  • an agent asking to work in their workspace on their behalf;
  • an agent provider asking to link their account, so its agents can act for them from now on;
  • or an agent that signed up on its own, with how many monitors and how much credit move into their workspace.

They type the code the agent showed them and press Authorize agent. The agent works in the workspace that is active when they authorize.

Safeguards:

  • Only the person signed in with the email the agent gave can authorize it.
  • A code works for 10 minutes, and a link locks after 5 wrong codes.
  • The first link of an agent provider always asks the user, even when the provider vouches for the email.
  • Codes, links and tokens are stored only as hashes.

Disconnect an agent

Settings → Connected agents lists the agents with access to the workspace, when they were authorized and when they were last active. Disconnect ends an agent's access tokens and identity assertion immediately; it must be authorized again to come back.

An agent can also revoke a single access token with POST /oauth2/revoke. An agent provider can revoke every token of a user it vouched for with a security event.

Limits

  • At most 5 anonymous sign-ups per IP address per hour, and 20 service_auth sign-ups.
  • An anonymous agent's claim window is 7 days. An unclaimed agent keeps working in its own workspace.
  • A request to act for a user expires after 24 hours if nobody authorizes it.
  • Identity assertions from agent providers are accepted only from providers on this service's trust list, with a sign-in at the provider less than an hour old.