// getting started

Authentication

Three surfaces, three credentials, and no overlap between them. Most integration failures here are one mistake: a secret that is perfectly valid somewhere else being presented to a surface that does not accept it. This page says which is which and what each refusal looks like.

01// the map

Three credentials, three surfaces

Surface	Credential	Where it comes from
`https://mcp.superagnt.com/mcp`	An OAuth 2.1 access token, or a workspace MCP bearer token	The client runs OAuth itself on first use. The bearer is minted in the dashboard for clients that cannot.
`https://api.superagnt.com/v1`	A workspace API key, sent as `Authorization: Bearer`	Minted with the workspace and managed in the dashboard.
`https://app.superagnt.com`	A signed-in session	Signing in. Session routes also require the workspace id, so a session alone does not reach another workspace.

They are not interchangeable in either direction. A workspace MCP bearer is refused on the REST API, and an API key is not what the MCP endpoint is asking for.

02// mcp

OAuth 2.1 for MCP

The MCP endpoint is its own authorization server, so a client that speaks OAuth needs the URL and nothing else. It discovers the endpoints, registers itself, and holds a credential you never see.

Capability	Detail
Authorization server metadata	`/.well-known/oauth-authorization-server`
Protected resource metadata	`/.well-known/oauth-protected-resource/mcp`, plus per-facet and per-server variants
Dynamic client registration	`/oauth/register`. Client ID Metadata Documents are accepted too, so a client with a fetchable metadata URL can skip registration entirely.
Grants	`authorization_code, refresh_token`
PKCE	`S256` only
Token endpoint auth	`none`, so public clients have no client secret to store or leak

discoverybash

# authorization server metadata (RFC 8414)
curl -sS https://mcp.superagnt.com/.well-known/oauth-authorization-server

# protected resource metadata for the canonical endpoint (RFC 9728)
curl -sS https://mcp.superagnt.com/.well-known/oauth-protected-resource/mcp

A client does not even need the discovery URLs up front. An unauthenticated call returns a 401 whose WWW-Authenticate header carries resource_metadata, so an OAuth-only client can bootstrap the whole flow from a failed request.

401 on the mcp endpointhttp

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.superagnt.com/.well-known/oauth-protected-resource/mcp",
  error="invalid_token", error_description="Missing Authorization header"

{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Missing Authorization header"}}

custom servers use the direct url

For a non-default (custom) server, point OAuth at that server's own per-server URL rather than the bare canonical one. The canonical URL sends no resource indicator, so consent preselects the workspace's default server and the client silently ends up connected to the wrong one.

03// rest

REST: Authorization: Bearer only

There is one way to authenticate a /v1 call. There is no x-api-key fallback on any /v1 path, so a client built against that header will get a 401 on every request no matter how valid its key is.

every authenticated callbash

curl -sS "https://api.superagnt.com/v1/credits" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

Keys are formatted agnt_live_ followed by 32 hexadecimal characters. Only a SHA-256 hash of the key is compared at authentication time, which is why a lost key is re-revealed from the dashboard rather than recomputed from anything the API stores in the clear.

A missing header, a header that is not Bearer <key>, an empty key, and an unknown or revoked key all come back the same way: 401 with error code UNAUTHORIZED.

04// key management

Managing API keys

Keys are created, re-revealed and revoked in the dashboard at app.superagnt.com. Those routes are session-authenticated, which means an API key cannot manage API keys: a leaked key cannot mint itself a replacement or revoke the keys around it.

A key belongs to one workspace, and inherits that workspace's organization for billing. Spend from the key lands in that organization's wallets.
last_used_at is stamped on every authenticated request, so an unused key is easy to spot before you rotate.
Revocation takes effect on the next request and cannot be undone. Issue a new key rather than trying to restore one.

deprecated

POST /v1/register is deprecated and is removed on 2026-12-31. Use the agnt_onboarding MCP tool instead, which records the same intent.

05// scopes

Scopes you will never create

Internally a key carries a scope, and only workspace keys are visible to the dashboard at all. The rest exist so the platform can attribute its own machinery, and every one of them is refused on the public API. You will see these names in error messages, never in your key list.

Scope	What it is	On /v1
`workspace`	The key you create and use	Accepted
`agent`	Minted for one deployed agent at runtime	403; must use `/runtime/*`
`data_job`	Short-lived, minted per data-job run	403; must use `/runtime/*`
`workspace_dryrun`	Injected into a builder dry-run sandbox	403; must use `/runtime/*`
`workspace_mcp`	The MCP endpoint's own bearer	403; unlocks the MCP endpoint only
`meta_agent`	Server-internal attribution for the Agnt Wizard	403; refused everywhere inbound

The consequence that matters: a sandbox credential that leaks out of a deployed agent cannot fan out across the rest of the API, and it cannot sidestep that agent's tool allowlist or mis-attribute its spend by calling /v1 directly.

06// no credential

Calling without credentials

A few surfaces need nothing at all, which is what lets an agent discover the platform before anyone has given it a key.

GET /health: liveness and the build the API is serving.
GET /v1/platforms and GET /v1/platforms/:slug: the catalog and its per-call prices.
GET /agent-setup/prompt.md: the served setup instructions an agent executes to wire itself up.

Everything else under /v1 answers a missing credential with more than a refusal. A 401 there also carries a how_to_get_access object with the MCP install URL, the signup URL, the docs index and the OpenAPI URL, so an agent that found the API on its own can route itself to access instead of stalling.

deprecated

The pre-/v1/data/* curated source paths (/v1/<slug>/*) return 410 with the replacement path and are removed on 2026-10-01.

Ready to wire a client up? Go to Connect your client, or start from the Quickstart. Nothing on this page is a live credential; every token slot prints <YOUR_MCP_TOKEN>.