Skip to Content
Skip to Content
Starcovery

Authentication

By Starcovery. Updated .

Search with no credential, then call the API with a Settings API key or an OAuth access token that a person issues from their Starcovery account.

Agents use Starcovery with no account of their own. Search needs no credential. Campaigns, keys, billing, and every other call that acts for an organization need a credential that a person issues from their Starcovery account: a Settings API key, which an organization owner mints in Settings > API Keys, or an OAuth access token from an MCP host. A person signs up on the web. One client IP makes at most 10 email sign-up attempts per 24 hours; past that, sign-up answers 429 with X-Retry-After in seconds.

Short path, with a Settings API key:

export STARCOVERY_TOKEN=<TOKEN>
npx starcovery whoami whoami

whoami whoami shows 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 the same steps over HTTP.

Discover

On a 401 from a gated endpoint (campaigns, keys, billing), read the WWW-Authenticate header. It contains resource_metadata, which points at the Protected Resource Metadata document. The Model Context Protocol (MCP) endpoint answers 401 to a credential it cannot verify, and to a tools/call without a credential for any tool except search_creators, enrich_creators, thread_turn, get_creator, list_published_searches, get_published_search, send_feedback, and request_hand_pick, with resource_metadata at /.well-known/oauth-protected-resource/api/mcp. You can also fetch the well-known URLs directly:

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

The second document names the authorization, token, and client registration endpoints. The token endpoint, /api/auth/oauth2/token, takes the authorization_code and refresh_token grants.

Get a credential

A person gives the agent one of these:

  • A Settings API key, which the person creates in Settings > API Keys.
  • An OAuth access token. An MCP host that supports OAuth signs in when prompted. The person approves the connection for one organization on the consent screen.

Install the host skill

Install the Starcovery skill with this installer. If bun is on PATH:

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

Otherwise:

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

If bunx, npx, or skills fails, warn and continue. Never write a token into the skill. Never write a project .cursor/skills directory by hand.

Claude Desktop has no skills CLI agent id. Download skill.zip and upload it at Customize > Skills with code execution on. MCP is a separate connector. See Call a creator database over MCP.

Call the API

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

An OAuth access token that was issued with a DPoP proof is sent as Authorization: DPoP <token> with a DPoP proof header whose htm and htu are the method and URL of that call, and works only that way. The x-api-key header accepts a Settings API key, and is read only when Authorization carries no Bearer or DPoP credential: a request with both headers is answered by Authorization alone. MCP accepts the same credentials. The MCP tools search_creators, enrich_creators, thread_turn, get_creator, list_published_searches, get_published_search, send_feedback, and request_hand_pick also work without a credential, and every other MCP tool requires one. See Call a creator database over MCP.

Scopes

The API takes one scope, organization. A credential acts for one organization: the one the person approved for an OAuth connection, or the one that owns the Settings API key.

Credential types

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

CredentialWho mints itWhere it works
Settings API keyAn organization owner, in Settings > API KeysREST, MCP, CLI, including /api/keys.
OAuth access tokenThe OAuth flow of an MCP client, after the consent screenAs Authorization: Bearer, never as x-api-key, at the endpoint it was issued for: REST and the CLI for https://www.starcovery.com/api/, or MCP for https://www.starcovery.com/api/mcp, which MCP hosts ask for. Not /api/keys.
Browser sessionWeb sign-in with Google, or with email and passwordweb and same-origin API calls. A request whose Origin or Sec-Fetch-Site header names another origin gets no session from the cookie.

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.

Only an organization owner creates keys. An admin or a member who asks /api/keys for a new key gets 403 with error api_key_owner_only. 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.

A Settings API key belongs to its organization and acts as the member who minted it, with that member's current role. It stops working once that member leaves the organization.

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 Settings API keys and OAuth access tokens unchanged.

Docs playground

The API playground starts with no credential. Paste a Settings API key into its authentication panel.