OAuth

Datatape implements the MCP OAuth specification so AI clients can authenticate users without manual token management. This page covers the protocol details.

Overview

The OAuth flow lets an AI client (like Claude Desktop) authenticate a user through their browser, receive tokens, and call MCP tools on behalf of that user. Datatape acts as an OAuth proxy, delegating identity to WorkOS AuthKit.

AI Client → Datatape MCP Server → WorkOS AuthKit → User's Browser

Discovery

Datatape exposes two well-known metadata endpoints per the relevant RFCs.

Protected Resource Metadata (RFC 9728)

GET https://<org-id>.mcp.datatape.ai/.well-known/oauth-protected-resource

Returns:

{
  "resource": "https://<org-id>.mcp.datatape.ai",
  "authorization_servers": ["https://<org-id>.mcp.datatape.ai"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"]
}

This tells the client where to find the authorization server and what scopes are available.

Authorization Server Metadata (RFC 8414)

GET https://<org-id>.mcp.datatape.ai/.well-known/oauth-authorization-server

Returns:

{
  "issuer": "https://<org-id>.mcp.datatape.ai",
  "authorization_endpoint": "https://<org-id>.mcp.datatape.ai/oauth/authorize",
  "token_endpoint": "https://<org-id>.mcp.datatape.ai/oauth/token",
  "registration_endpoint": "https://<org-id>.mcp.datatape.ai/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"]
}

Dynamic Client Registration (RFC 7591)

Clients register dynamically by posting to the registration endpoint:

POST /oauth/register
{
  "redirect_uris": ["http://localhost:12345/callback"],
  "client_name": "Claude Desktop"
}

Datatape returns a client_id that the client uses for the authorization flow. The registration is proxied — Datatape maps all dynamic registrations to its WorkOS OAuth application.

Authorization Flow

After registration, the client initiates a standard OAuth 2.0 authorization code flow with PKCE:

1. Client generates a code verifier and challenge (SHA-256, base64url-encoded)
2. Client redirects user to /oauth/authorize with code_challenge and code_challenge_method=S256
3. Datatape proxies to WorkOS AuthKit — the user sees a familiar sign-in page
4. WorkOS redirects back with an authorization code
5. Client exchanges the code at /oauth/token with the code_verifier
6. Datatape proxies to WorkOS and returns access + refresh tokens

PKCE (S256)

PKCE (Proof Key for Code Exchange) is required. Only the S256 method is supported. This prevents authorization code interception attacks, which is critical for native desktop apps that use localhost redirect URIs.

Token Refresh

Access tokens expire. Clients use the offline_access scope to receive a refresh token, then exchange it at /oauth/token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<token>&client_id=<client_id>

Datatape proxies the refresh request to WorkOS and returns new tokens. The offline_access scope is automatically injected during authorization if the client omits it.

How Claude Desktop Handles OAuth

Claude Desktop supports MCP OAuth natively. When you add a Datatape endpoint:

1. Claude discovers the OAuth metadata automatically
2. Claude registers as a client via Dynamic Client Registration
3. Claude opens your browser for sign-in
4. After sign-in, Claude receives tokens and starts calling tools
5. Claude refreshes tokens automatically when they expire

No manual token management is needed.

Organization-Level OAuth Control

OAuth can be enabled or disabled at the organization level. When disabled, the /.well-known/oauth-protected-resource endpoint returns 404, and clients must use agent API keys instead.