Get started

OAuth and dashboard sessions

The two credentials that are not API keys: OAuth for MCP clients, and the dashboard session behind the playground.

Most integrations authenticate with an API key. Two other credentials exist for specific surfaces, and neither is meant for your own server code.

OAuth (MCP clients only)#

Some MCP clients — Claude Desktop, claude.ai, a published ChatGPT connector — take a URL and an OAuth flow and have nowhere to put a custom header. For those, the MCP server runs the standard authorization-code flow with PKCE:

  1. The client discovers the authorization server from /.well-known/oauth-protected-resource.
  2. It registers itself dynamically.
  3. It sends you to a Sprouts consent screen.
  4. It receives a token bound to that server.

What you need to know about it from the API's side:

  • There is nothing to create and nothing to paste. You sign in and consent; no key is involved at any point.
  • The scopes are the same five, and no wider. An OAuth client asks for the scopes it needs from exactly the ceiling listed in Scopes.
  • Spend is attributed to the person who consented, not to a key, so these runs carry no key_id and do not appear under any key's GET /v1/keys/usage. They are in the tenant's balance and in usage history like everything else, and responses report meta.credential: "session" rather than "api_key".
  • The MCP server never passes your token through. It verifies the token it was given, checks that it was issued for that server specifically, and then exchanges it for a different one bound to this API. That is what the MCP specification requires of a resource server, and what stops a token minted for one Sprouts surface being spendable on another.
  • On the REST API, Authorization: Bearer carries only these OAuth tokens. The token issued for this API arrives as a Bearer token. An API key sent as Authorization: Bearer is not read as a key and gets the generic 401 auth.unauthorized: on REST, a key always goes in X-API-Key. The MCP server is the one exception on the client side. It accepts a key as a Bearer token and forwards it to the API as X-API-Key.

The dashboard session (playground only)#

The dashboard's in-app playground calls the same retrieval routes with the signed-in session cookie + CSRF header instead of a key. This path exists for interactive use only:

  • It is throttled per session: 30 requests/minute, 500/day, answered with 429 and a Retry-After header.
  • Responses say meta.credential: "session" instead of "api_key".
  • It still costs real credits and carries no integration compatibility guarantee — it is not in the public OpenAPI.

Anything automated builds against an API key. If a request presents both a key and a session cookie, the key wins. See Playground.