Sonar API Authentication

The Sonar REST API accepts three kinds of callers: API keys (the primary method), OAuth 2.0 access tokens (used by MCP clients that sign in via the browser), and a keyless anonymous free tier for a handful of stateless endpoints. All authenticated requests use the Authorization header — there are no query parameter or cookie schemes.

API keys

Pass your key as a bearer token on every request:

curl https://trysonar.app/api/v1/apps/search?term=meditation&store=ios \
  -H "Authorization: Bearer aso_your_api_key_here"

Keys are created at /developers in the dashboard and use the prefix aso_ followed by 64 hex characters. The full key is shown once at creation time — Sonar stores only its SHA-256 hash. Every key has the implicit read scope; mutating endpoints additionally require the write scope, chosen at issuance (see Scopes in the API reference).

OAuth 2.0

Sonar supports OAuth 2.0 bearer authentication for the hosted MCP endpoint and direct /api/v1 calls. OAuth-capable MCP clients (Claude Code, claude.ai connectors) need no API key at all: the first call to an account tool returns 401 + WWW-Authenticate, the client discovers the authorization server, registers itself via dynamic client registration, and opens the browser for consent. The granted access token then authenticates API requests exactly like a key, with read + write scopes for the organization the signed-in user owns.

Standard OAuth discovery metadata is published at:

https://trysonar.app/.well-known/oauth-protected-resource      (RFC 9728)
https://trysonar.app/.well-known/oauth-authorization-server   (RFC 8414)

The authorization, token, and registration endpoints named in that metadata handle the full authorization-code + PKCE flow. Tokens are meant for interactive sign-in flows — for scripts, CI, and server-side integrations, prefer API keys.

Anonymous free tier

A few stateless endpoints work with no Authorization header at all, rate-limited per IP per day: /apps/search, /apps/lookup, /apps/aso-score, /apps/extract-keywords, /keywords/suggestions, and /charts/top share 30 requests/day, while /keywords/metrics allows 5 keywords/day. Over the limit you get a 429 with signup instructions. Note that a present-but-invalid key is rejected with 401 — the free tier applies only when the header is truly absent.

Authentication errors

401 unauthorized — missing, invalid, or revoked credentials. 403 forbidden — valid credentials but a missing scope or a plan that doesn't cover the endpoint. See the full API reference for the complete error catalog, endpoint list, and the machine-readable OpenAPI 3.1 spec.