Delegated OAuth Configuration

Technical setup for drio apps that call protected APIs on behalf of signed-in users.

This page is for engineers and technical reviewers. Use it when a drio app needs to call a protected API with user-level authentication.

What This Enables

Delegated OAuth lets an MCP client sign the user in, obtain tokens through the configured auth flow, and retry the protected tool call with the right bearer token.

Endpoint Model

Each drio app has a public MCP host. This can be either:

https://{mcpId}.mcp.getdrio.com/mcp
https://customer.example.com/mcp

The wildcard *.mcp.getdrio.com host remains the fallback endpoint when no custom domain is active.

Auth discovery and OAuth routes are served on the same host:

/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
/.well-known/openid-configuration
/oauth/register
/oauth/authorize
/oauth/callback
/oauth/token

Inputs You Need Before Setup

a tool configured with API datasource mode
provider details for the upstream OAuth flow:
- client_id
- client_secret when required
- authorization_endpoint
- token_endpoint
- optional registration_endpoint
the provider scopes required by the upstream API

Configure Delegated OAuth In drio

open the datasource section in the tool editor
set auth mode to OAuth (Delegated)
fill in the authorization endpoint, token endpoint, client ID, and scopes
add optional values such as registration endpoint or provider-specific params when needed
save the tool settings and test the unauthenticated challenge flow

Runtime Flow

When an MCP client calls a protected tool without a token:

drio returns an auth challenge with MCP auth metadata
the client discovers metadata from the /.well-known/* routes
the client registers and starts OAuth through /oauth/register and /oauth/authorize
drio receives the upstream callback at /oauth/callback
the client exchanges the drio bridge code through /oauth/token
the client retries the tool call with the bearer token
drio forwards the authenticated request to the protected upstream API

Mermaid diagram source:

sequenceDiagram
  autonumber
  participant Client as MCP client
  participant Drio as drio MCP host
  participant OAuth as OAuth provider
  participant API as Protected upstream API

  Client->>Drio: Call protected tool without token
  Drio-->>Client: 401 + auth metadata
  Client->>Drio: Discover /.well-known metadata
  Client->>Drio: POST /oauth/register
  Client->>Drio: Start /oauth/authorize
  Drio->>OAuth: Redirect for authorization
  OAuth-->>Drio: Upstream authorization code callback
  Drio-->>Client: Redirect with drio bridge code
  Client->>Drio: POST /oauth/token
  Client->>Drio: Retry tool call with bearer token
  Drio->>API: Forward authenticated request
  API-->>Drio: Protected API response
  Drio-->>Client: Tool result

Verify The Setup

Replace the example host with either your wildcard MCP host or your active custom domain and confirm:

curl -i https://{mcpId}.mcp.getdrio.com/.well-known/oauth-protected-resource
curl -i https://customer.example.com/.well-known/oauth-authorization-server

Expected results:

both routes return 200
the metadata references valid URLs on the same tenant host
a protected tool call without auth returns a 401 challenge with resource_metadata

no sign-in prompt in the client: verify the 401 challenge includes resource_metadata
authorize works but token exchange fails: verify the registered redirect URI, token endpoint, client credentials, and accepted request format
metadata discovery fails: verify both canonical and compatibility /.well-known routes
the tool still executes anonymously: verify delegated OAuth is enabled on the datasource

Delegated OAuth Configuration

What This Enables

Endpoint Model

Inputs You Need Before Setup

Configure Delegated OAuth In drio

Runtime Flow

Verify The Setup

Provider Notes

WorkOS

Providers Without Dynamic Registration

Troubleshooting