Authentication
Authenticate MCP requests with agent API keys or OAuth.
Authentication
Every request to a Datatape MCP endpoint must be authenticated. Datatape supports two authentication methods: agent API keys and OAuth (JWT).
Agent API Keys
Each agent has an embedded API key generated at creation time. Use this key to authenticate programmatic requests to your org's MCP endpoint.
Authorization: Bearer dt_live_a1b2c3d4e5f6...All Datatape API keys use the dt_ prefix. This makes them easy to identify in configuration files and enables secret scanning tools (like GitHub's) to detect accidentally committed keys.
When to use agent keys:
- Configuring an AI client (Claude Desktop, Cursor) for programmatic access
- CI/CD pipelines and automation
- Server-to-server integrations
- Any access that should not require interactive login
Agent API keys do not carry user identity. The caller sees only the tools assigned to that specific agent. Audit logs show the agent name.
OAuth (Interactive Clients)
OAuth is the recommended method for interactive AI clients. Datatape implements the MCP OAuth specification so clients like Claude Desktop can authenticate users automatically.
The flow works like this:
- Client discovers OAuth metadata via
/.well-known/oauth-protected-resource - Client registers dynamically via
/oauth/register - User is redirected to sign in with WorkOS AuthKit
- Client receives an access token and refresh token
- Subsequent requests use the access token as a Bearer token
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...Datatape verifies the JWT signature using WorkOS JWKS (cached for performance) and checks that the user belongs to the organization.
When authenticated via OAuth, the user sees the tools assigned to them — either directly, through toolsets, or through group memberships.
You do not need to manage JWT tokens manually. OAuth-capable clients handle token acquisition and refresh automatically.
For the user-level endpoint (my.mcp.datatape.ai), OAuth is the only supported authentication method.
For full details, see OAuth.
Choosing an Auth Method
| Method | Best For | User Identity | Auto-Refresh |
|---|---|---|---|
| OAuth/JWT | Claude Desktop, Cursor, interactive clients | Yes | Yes |
| Agent Key | Automation, CI/CD, server-to-server | No (agent identity) | N/A |
Decision Guide
- Using Claude Desktop or another OAuth-capable client? Use OAuth. It handles authentication automatically and ties requests to a user identity.
- Building an integration or automation? Create an agent, assign it the tools it needs, and use the agent API key.
- Need to share access without user accounts? Use an agent API key. Anyone with the key can call the tools assigned to that agent.
Treat API keys like passwords. Do not commit them to source control or share them in chat. Rotate keys from the agent detail page in the dashboard.
Authentication Errors
When authentication fails, the MCP endpoint returns HTTP 401 with a WWW-Authenticate header:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
error_description="Token expired or invalid",
resource_metadata="https://<org-id>.mcp.datatape.ai/.well-known/oauth-protected-resource"OAuth-capable clients use the resource_metadata URL to discover how to obtain a new token and retry automatically.