> ## Documentation Index > Fetch the complete documentation index at: https://starcovery.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Authentication > Register an identity with no human in the loop, exchange it for an access token, and hand ownership to a person later. 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](https://www.starcovery.com/app/settings/api-keys). The short path is one CLI call: ```bash theme={null} npx starcovery auth register ``` The rest of this page is the same protocol over plain HTTP. 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: ```bash theme={null} curl https://www.starcovery.com/.well-known/oauth-protected-resource curl https://www.starcovery.com/.well-known/oauth-authorization-server ``` 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. 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`. ```bash theme={null} curl -X POST https://www.starcovery.com/agent/identity \ -H "content-type: application/json" \ -d '{"type": "anonymous"}' ``` An optional referral code grants double-sided credits for referrer and referee: ```json theme={null} { "type": "anonymous", "ref": "YOURCODE" } ``` 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`. ```bash theme={null} curl -X POST https://www.starcovery.com/oauth2/token \ -H "content-type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \ --data-urlencode "assertion=" ``` 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. ```bash theme={null} curl "https://www.starcovery.com/api/search?q=space+and+astronomy+explainers" \ -H "Authorization: Bearer " ``` The `x-api-key` header is accepted as well, with the same token. MCP requires a credential too; see [Connect over MCP](/docs/guides/mcp). ## Claim ceremony (optional) Run the claim only when a human wants to own the account. Ask the service to start the ceremony: ```bash theme={null} curl -X POST https://www.starcovery.com/agent/identity/claim \ -H "content-type: application/json" \ -d '{"claim_token": "...", "email": "person@their-inbox.com"}' ``` 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`: ```bash theme={null} curl -X POST https://www.starcovery.com/oauth2/token \ -H "content-type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=urn:workos:agent-auth:grant-type:claim" \ --data-urlencode "claim_token=..." ``` 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 | Credential | Who mints it | Where it works | | ------------------ | ----------------------------------------------------------------------- | -------------------------------------------------- | | Agent access token | `POST /agent/identity` + token exchange | REST, MCP, CLI. No free search grant before claim. | | Settings API key | Humans, at [Settings](https://www.starcovery.com/app/settings/api-keys) | REST, MCP, CLI, including `/api/keys`. | | Browser session | Web sign-in | Web app and same-origin API calls. |