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.

Connected X account

Separate OAuth 1.0a authorization and capability grants

X account operations use a separate OAuth 1.0a connection created in Account settings. Soundside keeps X credentials server-side; they do not need routine refresh and agents never receive them. An API key or verified OAuth client needs explicit read, publish, or manage capability grants. Reconnecting or disconnecting X revokes those unattended grants. See X account operations for the action contract.

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.