Skip to main content
Starcovery supports agentic registration through the open auth.md protocol. An agent gets a working credential without human involvement, spends immediately, and can hand ownership to a person later. Humans can follow the same path, or sign up on the web and mint a durable API key in Settings. The short path is one CLI call:
The rest of this page is the same protocol over plain HTTP.
1

Discover

On a 401 from a gated endpoint (campaigns, MCP, keys, billing), read the WWW-Authenticate header. It carries resource_metadata pointing at the Protected Resource Metadata document. You can also fetch the well-known URLs directly:
The second document carries the agent_auth block. agent_auth.identity_endpoint and agent_auth.claim_endpoint are the registration and claim URLs below. identity_types_supported lists which registration methods the service accepts.
2

Pick a method

The service accepts one identity type: anonymous. Registering with service_auth returns 400 service_auth_not_enabled; identity_assertion returns 400 issuer_not_enabled. Both are terminal: fall back to anonymous.
3

Register anonymously

An optional referral code grants double-sided credits for referrer and referee:
CLI: starcovery auth register --ref YOURCODE (or the STARCOVERY_REF environment variable). Invalid codes do not fail registration.The response carries registration_id, a service-signed identity_assertion with assertion_expires, pre_claim_scopes, and claim materials: claim_url, claim_token, claim_token_expires, and post_claim_scopes.
The claim_token is returned once. Hold it as long as a human may want ownership of this identity.
Registrations are capped at 100 per UTC day. Past the cap the endpoint answers 429 with error rate_limited.
4

Exchange the assertion for an access token

The response is a bearer access_token with expires_in. Re-run the exchange with the same identity_assertion when the access token expires. There is no refresh token: the assertion is the long-lived half. Each exchange retires the previous token, so hold exactly one and re-fetch when it lapses.
5

Call the API

The x-api-key header is accepted as well, with the same token. MCP requires a credential too; see Connect over MCP.

​
Claim ceremony (optional)

Run the claim only when a human wants to own the account. Ask the service to start the ceremony:
The response carries a claim_attempt block with a 6-digit user_code, verification_uri, expires_in, and interval. Starcovery emails a one-time link to the supplied address. The emailed link is the half you never see; the user_code travels only through you. Neither channel alone finishes the ceremony: the mailbox proves the human identity. Tell the person in one message: open the link emailed to them, then enter the 6-digit code. They set a password on that page and the account is theirs. Disposable, reserved, or undeliverable addresses return undeliverable_email before initiation. If the claim returns mail_send_failed, ask for a deliverable inbox and retry. Poll the token endpoint until it stops answering authorization_pending, honoring interval:
On success you receive a post-claim access_token and a fresh identity_assertion. Pre-claim access tokens are revoked at that moment: drop them and use the new one. If the user_code window closes, call the claim endpoint again with the same claim_token and email for a fresh code. The new code and link replace the previous pair immediately.

​
Scopes

Registration returns pre_claim_scopes and post_claim_scopes; on this service they are the same set. Claiming does not widen API access. It gives a human the account (sign-in, credit packs, billing) while the credential, credits, and history carry over. The user id never changes.

​
Credential types at a glance