# SosoAPI auth.md You are an agent acting for a SosoAPI user, or an application developer building their personal assistant. Reuse a working SosoAPI connection. For a new hosted connection, give your MCP host https://sosoapi.ai and select OAuth with automatic client registration. The host normally performs the protocol below without asking for an API key. Local Claude Code and Codex setup: https://sosoapi.ai/setup.md. Supported registration methods: user_delegated OAuth 2.0 Dynamic Client Registration (RFC 7591), followed by authorization_code with PKCE S256 and human consent. Credential types: Bearer access_token and refresh_token. This is public-client OAuth; no client secret or password grant is required. Do not register clients, create accounts or issue credentials during a passive readiness scan. ## Step 1 — Register and provision a credential Client registration begins this flow. The person must complete OAuth consent before an access credential is issued; a registered client_id is not a credential. ### 1.1. Discover the resource and authorization server Protected resource: https://sosoapi.ai (the exact audience has no trailing slash). Protected Resource Metadata: https://sosoapi.ai/.well-known/oauth-protected-resource. Authorization server issuer: https://gqeshlawtcexsapabaui.supabase.co/auth/v1. OIDC discovery: https://gqeshlawtcexsapabaui.supabase.co/auth/v1/.well-known/openid-configuration. Use the discovered authorization_endpoint, token_endpoint, registration_endpoint and jwks_uri; verify the issuer before sending an authorization code or token. The legacy resource https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp remains supported with its own metadata at https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp/.well-known/oauth-protected-resource. Keep existing connections and their credentials bound to their original resource. A new root connection must obtain an access token authorized for the exact root audience. The same issuer serves both. ### 1.2. Register this assistant's public OAuth client Registration endpoint: POST https://gqeshlawtcexsapabaui.supabase.co/auth/v1/oauth/clients/register. Content-Type: application/json. No bearer token or client secret is needed for dynamic client registration. Register once, save the returned client_id, and reuse it. Replace the example callback with the exact HTTPS callback controlled by your MCP host; do not use example.com, a guessed callback or a wildcard. Request body: ```json { "client_name": "My SosoAPI Assistant", "redirect_uris": ["https://your-assistant.example/oauth/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"] } ``` The successful JSON response contains client_id and the accepted client metadata. The client_id identifies this client; it is not an API credential. Registration creates an OAuth client, not a user account, Workspace, social connection or publishing grant. On a non-success response, report the status and safe error code; do not invent a client ID or repeatedly register replacement clients. ### 1.3. Ask the person to sign in and authorize Generate a fresh cryptographically random state and a 43–128 character PKCE code_verifier. Keep them in the host's protected, short-lived login state. Set code_challenge to the unpadded base64url SHA-256 digest of that verifier. Open the discovered authorization_endpoint (currently https://gqeshlawtcexsapabaui.supabase.co/auth/v1/oauth/authorize) in the person's browser with these URL-encoded query parameters: ```text response_type=code client_id= redirect_uri= scope=openid email profile state= code_challenge= code_challenge_method=S256 ``` The person signs in or creates their own SosoAPI account and approves or denies OAuth access. Keep their original approval URL and return destination. Never enter their credentials, approve for them or substitute a maintainer account. Pause the dependent step while they finish; resume the original task afterward. The callback receives code and state, or an OAuth error. Verify state exactly against the pending login before using code. Reject a mismatch or denial. Do not send the authorization code, verifier or returned tokens to another origin. ### 1.4. Exchange the code for credentials Token endpoint: POST https://gqeshlawtcexsapabaui.supabase.co/auth/v1/oauth/token. Content-Type: application/x-www-form-urlencoded. Send URL-encoded form fields: ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= ``` Do not send a client_secret for this public client. Do not follow token-endpoint redirects. The successful JSON response supplies access_token, token_type=bearer, expires_in and refresh_token; use the returned lifetime rather than assuming it. An id_token, when returned, describes identity and is not an MCP access token. Store credentials in the host's secure credential store, never in prompts, chat, logs or URLs. A token response does not grant Workspace actions by itself. ## Step 2 — Use the credential and finish SosoAPI consent Send MCP Streamable HTTP requests to POST https://sosoapi.ai, with these headers: ```http Authorization: Bearer Content-Type: application/json Accept: application/json, text/event-stream ``` Use your MCP client's initialize and tools/list sequence. If the available tool is sosoapi_authorize, call it to get the real approval URL. The person chooses the Workspaces and actions there; after approval, reconnect the MCP server and read authenticated context again. This consent is separate from OAuth sign-in. The service verifies identity, live session, client, resource audience and Workspace/action grants. OIDC scopes openid email profile describe identity; they do not grant publishing or access to every Workspace. Return only the capabilities actually authorized. A 401 may require refresh or sign-in; 403 or a denied grant is not permission to widen access. Never forward tokens to arbitrary tools or switch endpoints to evade a denial. A failed or uncertain publishing operation must be reconciled before another submission. ## Step 3 — Refresh and revoke credentials For refresh, POST the same token endpoint with Content-Type: application/x-www-form-urlencoded and these fields: ```text grant_type=refresh_token client_id= refresh_token= ``` Save the new access_token and expiry; atomically replace refresh_token if the response rotates it. Do not race refresh requests. A definitive invalid_grant requires a new human sign-in; transient failures are not proof of revocation. To revoke this assistant session's SosoAPI delegated access, send POST https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/agent-auth/revoke-current with Authorization: Bearer , Content-Type: application/json, and JSON body {}. This ends the calling session's SosoAPI grants and associated agent keys. It does not revoke other sessions or delete the OAuth client or user. Require a successful response before claiming server revocation. Disconnect the host's MCP connection and clear its stored credentials when logout is confirmed. Do not run revocation during a passive scan or while merely reading this guide. For an existing local CLI session, use npx -y sosoapi auth status; when the person requests logout, npx -y sosoapi auth logout performs server revocation before clearing local credentials. Never read or print its credential file. ## Other integrations and protocol boundaries Ordinary MCP onboarding needs no API key. Existing developer API integrations may use a user-created, least-privilege personal access token following https://sosoapi.ai/docs/authentication. Do not ask anyone to paste tokens into chat. This service uses the existing Supabase OAuth issuer; https://sosoapi.ai is a resource, not a second issuer. The supported registration and credential flow is the public-client, human-authorized OAuth recipe above. The person retains control of account sign-in and Workspace/action consent throughout that flow. Skill: https://sosoapi.ai/skills/sosoapi/SKILL.md API contract: https://sosoapi.ai/docs/openapi.json