# SocialGlass authentication

SocialGlass uses OAuth for its remote MCP server. Agents must authenticate as a SocialGlass user and can access only the organizations and operations allowed for that user.

## Discover

- Endpoint: https://mcp.socialglass.ai/mcp
- Server card: https://mcp.socialglass.ai/.well-known/mcp.json
- Protected-resource metadata: https://mcp.socialglass.ai/.well-known/oauth-protected-resource
- Path-specific metadata: https://mcp.socialglass.ai/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://clerk.socialglass.ai/.well-known/oauth-authorization-server
- Setup guide: https://docs.socialglass.ai/reference/mcp-setup

Read the protected-resource metadata first, then follow its `authorization_servers` link. Do not hardcode authorization endpoints when discovery metadata is available.

## Pick a method

Use OAuth authorization code flow with PKCE S256 for a remote MCP client. Request the `openid`, `profile`, `email`, and `offline_access` scopes. The OIDC and refresh-token scopes support client authentication and session renewal; they do not broaden SocialGlass data access. If a workspace has Clerk user API keys enabled, a compatible client can instead use a key with the `social-glass:mcp` scope as a bearer token.

## Register

SocialGlass identifies OAuth clients with Client ID Metadata Documents (CIMD): the client's `client_id` is the HTTPS URL of its published metadata document. Dynamic Client Registration is turned off, so the authorization server advertises no registration endpoint. Only approved clients can sign in. Claude, Claude Code, ChatGPT, and Codex are approved. To approve another client, email the SocialGlass team with its metadata URL.

## Claim

Create a fresh PKCE verifier and challenge, then open https://clerk.socialglass.ai/oauth/authorize with the client's `client_id`, the registered `redirect_uri`, `response_type=code`, requested scopes, `prompt=consent`, a random `state`, and the protected resource https://mcp.socialglass.ai/mcp. Explicit consent is required when requesting `offline_access`. The signed-in user must approve the request; that user identity and its organization memberships define the available SocialGlass data.

~~~json
{
  "code_challenge": "<generated S256 challenge>",
  "code_challenge_method": "S256",
  "prompt": "consent",
  "resource": "https://mcp.socialglass.ai/mcp",
  "scope": "openid profile email offline_access"
}
~~~

## Use credential

Verify the returned `state`, then exchange the authorization code at https://clerk.socialglass.ai/oauth/token using the same `redirect_uri` and PKCE `code_verifier`. Also send `resource=https://mcp.socialglass.ai/mcp` again in the token request so the access token is bound to the MCP resource. Send that token as `Authorization: Bearer <token>` to https://mcp.socialglass.ai/mcp. Call `get_context` before other SocialGlass tools. Never place bearer tokens, API keys, passwords, or private keys in prompts, URLs, email, logs, or bug reports.

## Errors

A `401 Unauthorized` response includes a `WWW-Authenticate` challenge that points clients to the protected-resource metadata. Refresh or repeat OAuth once, then ask the user to reconnect if authorization still fails. A `403 Forbidden` response means the authenticated user does not have permission for the requested scope or organization; do not retry it as another organization.

## Revocation

When the user disconnects SocialGlass, revoke the token at https://clerk.socialglass.ai/oauth/token/revoke and remove locally stored access tokens, refresh tokens, PKCE material, and registration state. Do not log the token during revocation.
