Authentication

Starcovery supports agentic registration through the auth.md protocol. An agent can register, receive a credential, and spend without a human present. A human can claim the account later. Humans can also sign up on the web and mint a Settings API key in Settings > API Keys.

Short path:

npx starcovery auth login

This opens browser OAuth and saves a refreshable credential. For agentic registration without a human browser:

npx starcovery auth register

Use npx starcovery whoami to see the current credential, the bound user and organization, and whether the next search uses the user's free grant or the organization's prepaid credits.

The rest of this page describes agentic registration over HTTP.

curl https://www.starcovery.com/.well-known/oauth-protected-resource
curl https://www.starcovery.com/.well-known/oauth-authorization-server

curl -X POST https://www.starcovery.com/agent/identity \
  -H "content-type: application/json" \
  -d '{"type": "anonymous"}'

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=<identity_assertion>"

bunx skills add https://www.starcovery.com --global --yes --skill starcovery --agent cursor --agent claude-code --agent codex

npx -y skills add https://www.starcovery.com --global --yes --skill starcovery --agent cursor --agent claude-code --agent codex

curl "https://www.starcovery.com/api/search?q=space+and+astronomy+explainers" \
  -H "Authorization: Bearer <access_token>"

Claim ceremony (optional)Copy Anchor Link

Run the claim only when a human wants to own the account:

curl -X POST https://www.starcovery.com/agent/identity/claim \
  -H "content-type: application/json" \
  -d '{"claim_token": "<claim_token>", "email": "<email_address>"}'

The response contains a claim_attempt block with verification_uri, expires_in, and interval. Starcovery emails a one-time link to the supplied address. The link contains a one-time token. Starcovery uses control of that mailbox to verify a human identity.

Tell the person: open the emailed link. On that page they sign in with Google using that email address, then press Claim This Account. The account is then theirs.

Disposable, reserved, or undeliverable addresses return undeliverable_email before initiation.

Poll the token endpoint until it stops answering authorization_pending, honoring interval:

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=<claim_token>"

The claim completes when the person presses Claim This Account, before your next poll. From that moment the pre-claim access tokens answer 401 and the pre-claim identity_assertion no longer exchanges. The next poll returns a post-claim access_token and a fresh identity_assertion. Use both from then on.

If the claim link window closes, call the claim endpoint again with the same claim_token and email address for a fresh link. The new link replaces the previous one immediately.

Claim initiation per registration is capped at 3 per rolling 24 hours. Past the cap the endpoint returns 429 with error rate_limited. Honor Retry-After.

ScopesCopy Anchor Link

Registration returns pre_claim_scopes and post_claim_scopes. On this service they are the same set, so claiming leaves API access unchanged.

Claiming gives a human the account: sign-in, credit packs, and billing. The credential, credits, and history remain in place, and the user id stays the same.

Credential typesCopy Anchor Link

The following table lists who mints each credential and where it works.

Every credential is bound to one organization. Spend, campaign visibility, and API key ownership all follow that organization. MCP OAuth access tokens and /api/auth/oauth2/userinfo include an organization_id claim.

Authorization embeds the organization that is active at consent time, or the caller's first organization when none is active. An issued token stays bound to that organization when the session's active organization changes.

To bind a different organization, pick it under Give access to on the consent screen when you authorize. You can also switch the active organization from the Organizations menu in the app sidebar before you authorize. Then replace the token.

/api/keys is the only surface for creating, listing, and revoking Settings API keys. The Better Auth /api-key/create, /api-key/delete, /api-key/get, /api-key/list, /api-key/update, and /api-key/verify routes are disabled and respond 404. Send API key requests to /api/keys with a browser session or a Settings API key.

An owner or admin lists and revokes every key of the organization. A member lists and revokes only the keys that member minted, and a revoke of another member's key returns 404.

Humans sign in on the web with Google, or with an email address and a password at Sign in. A password account confirms its email address through a mailed link before it can sign in. Forgot password mails a reset link.

Google is a trusted Better Auth provider. If a Google account's verified email matches an existing user whose email is already verified, Starcovery links the Google identity to that account instead of creating a duplicate. This linking leaves agent access tokens, Settings API keys, and OAuth access tokens unchanged.

Docs playgroundCopy Anchor Link

The API playground starts with no credential. Paste a Settings API key or an agent access token into its authentication panel.