Docs / Auth & Security

Authentication, discovery, and operational controls

Auth primitives, runtime safety signals, and access patterns for integrating Soundside as a remote MCP server.

When to use

Use this when integrating a new client

This page covers the auth primitives needed before any production MCP call: discovery endpoints, bearer usage, and mode selection between OAuth and API keys.

Discovery

OAuth discovery endpoints

GET https://mcp.soundside.ai/.well-known/oauth-protected-resource/mcp
GET https://mcp.soundside.ai/.well-known/oauth-authorization-server

Third-party connectors should prefer OAuth. Controlled first-party integrations can use API keys.

Request example

Bearer auth on MCP call

Authorization: Bearer <token>
Content-Type: application/json

Error behaviors

Auth-related failure modes

  • • Invalid or expired credentials return authorization errors.
  • • Untrusted OAuth client state can return policy-denied responses.
  • • Missing resource indicators in OAuth flows can block token usability.

Wallet auth

Wallet-based authentication (SIWE + Magic Link)

Wallet users created through x402 payments have full Supabase accounts. Two flows grant browser access:

  • • SIWE (browser) — The login page at /login includes a "Continue with Wallet" button. Connect a wallet extension (MetaMask, Coinbase Wallet), sign a message, and get a session.
  • • Magic Link (x402) — After an x402 payment, the tool response includes a wallet_link URL. Visiting it creates a session automatically — no wallet extension needed. 15-minute TTL, single-use.

Both flows produce the same Supabase session tied to the same deterministic wallet identity (UUID5 of wallet address). All assets generated via x402 payments appear in the user's library.

Runtime safety

Machine-readable error and quota signaling

Clients receive structured denial payloads and standard rate-limit headers for adaptive behavior.

Error contract

Responses include error_code, error_description, actionable_next_step, and retryable.

Rate-limit headers

Responses expose RateLimit-*, X-RateLimit-*, and Retry-After on quota denials.

Operational notes

Recommended auth policy

  • • Use OAuth for external integrations and partner connectors.
  • • Use API keys for first-party controlled service-to-service paths (/docs/api-keys).
  • • Use wallet auth for x402 payment users who need browser access to their library.
  • • Keep credentials scoped to only the required runtime surface.
  • • For client-specific setup, see /docs/integrations.