OAuth Integration

OAuth Flow Overview

Agent Dojo manages the full OAuth 2.0 authorization code flow on your behalf. This allows your tools to access third-party services like Google, GitHub, and Slack without you handling token exchange and refresh logic manually.

The flow consists of four steps:

Step 1: Initialize OAuth

Start the OAuth flow by requesting an authorization URL. Provide the provider and the redirect URI where the user will be sent after authorizing.

curl -X POST https://api.agentdojo.dev/mcp/oauth/init \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "provider_github_001",
    "redirect_uri": "https://your-app.com/oauth/callback",
    "scopes": ["repo", "user:email"]
  }'

Response:

{
  "auth_url": "https://github.com/login/oauth/authorize?client_id=...&redirect_uri=...&scope=repo+user:email&state=abc123",
  "state": "abc123",
  "expires_in": 600
}

Step 2: User Authorizes

Redirect the user to the auth_url returned in Step 1. The user will be prompted to grant your application access. After authorizing, they are redirected to your redirect_uri with an authorization code appended as a query parameter.

# User is redirected to:
https://your-app.com/oauth/callback?code=AUTH_CODE_HERE&state=abc123

Step 3: Handle Callback

When the user is redirected back to your application, forward the authorization code and state to Agent Dojo:

curl -X POST https://api.agentdojo.dev/mcp/oauth/callback \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTH_CODE_HERE",
    "state": "abc123"
  }'

Response:

{
  "status": "code_received",
  "message": "Authorization code received. Call /mcp/oauth/exchange-token to complete."
}

Step 4: Exchange Token

Exchange the authorization code for access and refresh tokens:

curl -X POST https://api.agentdojo.dev/mcp/oauth/exchange-token \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "abc123"
  }'

Response:

{
  "credential_id": "cred_github_001",
  "status": "active",
  "provider_id": "provider_github_001",
  "scopes": ["repo", "user:email"],
  "expires_at": "2026-02-15T10:30:00Z"
}

Checking OAuth Status

Check the current status of an OAuth flow or credential:

curl -X POST https://api.agentdojo.dev/mcp/oauth/status \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "abc123"
  }'

Response:

{
  "status": "active",
  "credential_id": "cred_github_001",
  "provider_id": "provider_github_001",
  "scopes": ["repo", "user:email"],
  "expires_at": "2026-02-15T10:30:00Z"
}

Refreshing Tokens

When an access token expires, use the refresh endpoint to obtain a new one. Agent Dojo handles the refresh token exchange with the provider.

curl -X POST https://api.agentdojo.dev/mcp/oauth/refresh-token \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "cred_github_001"
  }'

Response:

{
  "credential_id": "cred_github_001",
  "status": "active",
  "expires_at": "2026-03-15T10:30:00Z"
}

Canceling an OAuth Flow

Cancel an in-progress OAuth flow before it completes:

curl -X POST https://api.agentdojo.dev/mcp/oauth/cancel \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "abc123"
  }'

Response:

{
  "status": "canceled",
  "message": "OAuth flow has been canceled"
}

Next Steps