AutoGPT Platform OAuth Integration Guide

This guide explains how to integrate your application with AutoGPT Platform using OAuth 2.0. OAuth can be used for API access, Single Sign-On (SSO), or both.

For general API information and endpoint documentation, see the API Guide and the Swagger documentation.

Overview

AutoGPT Platform's OAuth implementation supports multiple use cases:

OAuth for API Access

Use OAuth when your application needs to call AutoGPT APIs on behalf of users. This is the most common use case for third-party integrations.

When to use:

• Your app needs to run agents, access the store, or manage integrations for users
• You want user-specific permissions rather than a single API key
• Users should be able to revoke access to your app

SSO: "Sign in with AutoGPT"

Use SSO when you want users to sign in to your app through their AutoGPT account. Request the IDENTITY scope to get user information.

When to use:

• You want to use AutoGPT as an identity provider
• Users already have AutoGPT accounts and you want seamless login
• You need to identify users without managing passwords

Note: SSO and API access can be combined. Request IDENTITY along with other scopes to both authenticate users and access APIs on their behalf.

Integration Setup Wizard

A separate flow that guides users through connecting third-party services (GitHub, Google, etc.) to their AutoGPT account. See Integration Setup Wizard below.

Prerequisites

Before integrating, you need an OAuth application registered with AutoGPT Platform. Contact the platform administrator to obtain:

• Client ID - Public identifier for your application
• Client Secret - Secret key for authenticating your application (keep this secure!)
• Registered Redirect URIs - URLs where users will be redirected after authorization

OAuth Flow

The OAuth flow is technically the same whether you're using it for API access, SSO, or both. The main difference is which scopes you request.

Step 1: Redirect User to Authorization

Redirect the user to the AutoGPT authorization page with the required parameters:

https://platform.agpt.co/auth/authorize?
  client_id={YOUR_CLIENT_ID}&
  redirect_uri=https://yourapp.com/callback&
  scope=EXECUTE_GRAPH READ_GRAPH&
  state={RANDOM_STATE_TOKEN}&
  code_challenge={PKCE_CHALLENGE}&
  code_challenge_method=S256&
  response_type=code

Parameters

Step 2: Handle the Callback

After the user approves (or denies) access, they'll be redirected to your redirect_uri:

Success:

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_TOKEN

Error:

https://yourapp.com/callback?error=access_denied&error_description=User%20denied%20access&state=RANDOM_STATE_TOKEN

Always verify the state parameter matches what you sent in Step 1.

Step 3: Exchange Code for Tokens

Exchange the authorization code for access and refresh tokens:

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "{AUTHORIZATION_CODE}",
  "redirect_uri": "https://yourapp.com/callback",
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}",
  "code_verifier": "{PKCE_VERIFIER}"
}

Response:

{
  "token_type": "Bearer",
  "access_token": "agpt_xt_...",
  "access_token_expires_at": "2025-01-15T12:00:00Z",
  "refresh_token": "agpt_rt_...",
  "refresh_token_expires_at": "2025-02-14T12:00:00Z",
  "scopes": ["EXECUTE_GRAPH", "READ_GRAPH"]
}

Step 4: Use the Access Token

Include the access token in API requests:

GET /external-api/v1/blocks
Authorization: Bearer agpt_xt_...

For SSO: If you requested the IDENTITY scope, fetch user info to identify the user:

GET /external-api/v1/me
Authorization: Bearer agpt_xt_...

Response:

{
  "id": "user-uuid",
  "name": "John Doe",
  "email": "[email protected]",
  "timezone": "Europe/Amsterdam"
}

See the Swagger documentation for all available endpoints.

Step 5: Refresh Tokens

Access tokens expire after 1 hour. Use the refresh token to get new tokens:

POST /api/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "agpt_rt_...",
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}"
}

Response:

{
  "token_type": "Bearer",
  "access_token": "agpt_xt_...",
  "access_token_expires_at": "2025-01-15T13:00:00Z",
  "refresh_token": "agpt_rt_...",
  "refresh_token_expires_at": "2025-02-14T12:00:00Z",
  "scopes": ["EXECUTE_GRAPH", "READ_GRAPH"]
}

Integration Setup Wizard

The Integration Setup Wizard guides users through connecting third-party services (like GitHub, Google, etc.) to their AutoGPT account. This is useful when your application needs users to have specific integrations configured.

Redirect to the Wizard

https://platform.agpt.co/auth/integrations/setup-wizard?
  client_id={YOUR_CLIENT_ID}&
  providers={BASE64_ENCODED_PROVIDERS}&
  redirect_uri=https://yourapp.com/callback&
  state={RANDOM_STATE_TOKEN}

Parameters

Provider Configuration

The providers parameter is a Base64-encoded JSON array:

const providers = [
  { provider: 'github', scopes: ['repo', 'read:user'] },
  { provider: 'google', scopes: ['https://www.googleapis.com/auth/calendar'] },
  { provider: 'slack' }  // Uses default scopes
];

const providersBase64 = btoa(JSON.stringify(providers));

Handle the Callback

After setup completes:

Success:

https://yourapp.com/callback?success=true&state=RANDOM_STATE_TOKEN

Failure/Cancelled:

https://yourapp.com/callback?success=false&state=RANDOM_STATE_TOKEN

Provider Scopes Reference

When using the Integration Setup Wizard, you need to specify which scopes to request from each provider. Here are common providers and their scopes:

GitHub

Documentation: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps

Example:

{ provider: 'github', scopes: ['repo', 'read:user'] }

Google

Documentation: https://developers.google.com/identity/protocols/oauth2/scopes

Example:

{ provider: 'google', scopes: ['https://www.googleapis.com/auth/calendar'] }
// Or use defaults (email, profile, openid):
{ provider: 'google' }

Notion

Documentation: https://developers.notion.com/reference/capabilities

Notion uses a single OAuth scope that grants access based on pages the user selects during authorization.

Linear

Documentation: https://developers.linear.app/docs/oauth/authentication

PKCE Implementation

PKCE (Proof Key for Code Exchange) is required for all authorization requests. Here's how to implement it:

JavaScript Example

async function generatePkce() {
  // Generate a random code verifier
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  const verifier = Array.from(array, b => b.toString(16).padStart(2, '0')).join('');

  // Create SHA-256 hash and base64url encode it
  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
  const challenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');

  return { verifier, challenge };
}

// Usage:
const pkce = await generatePkce();
// Store pkce.verifier securely (e.g., in session storage)
// Use pkce.challenge in the authorization URL

Python Example

import hashlib
import base64
import secrets

def generate_pkce():
    # Generate a random code verifier
    verifier = secrets.token_urlsafe(32)

    # Create SHA-256 hash and base64url encode it
    digest = hashlib.sha256(verifier.encode()).digest()
    challenge = base64.urlsafe_b64encode(digest).decode().rstrip('=')

    return verifier, challenge

# Usage:
verifier, challenge = generate_pkce()
# Store verifier securely in session
# Use challenge in the authorization URL

Token Management

Token Lifetimes

Token Introspection

Check if a token is valid:

POST /api/oauth/introspect
Content-Type: application/json

{
  "token": "agpt_xt_...",
  "token_type_hint": "access_token",
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}"
}

Response:

{
  "active": true,
  "scopes": ["EXECUTE_GRAPH", "READ_GRAPH"],
  "client_id": "agpt_client_...",
  "user_id": "user-uuid",
  "exp": 1705320000,
  "token_type": "access_token"
}

Token Revocation

Revoke a token when the user logs out:

POST /api/oauth/revoke
Content-Type: application/json

{
  "token": "agpt_xt_...",
  "token_type_hint": "access_token",
  "client_id": "{YOUR_CLIENT_ID}",
  "client_secret": "{YOUR_CLIENT_SECRET}"
}

Security Best Practices

1. Store client secrets securely - Never expose them in client-side code or version control
2. Always use PKCE - Required for all authorization requests
3. Validate state parameters - Prevents CSRF attacks
4. Use HTTPS - All production redirect URIs must use HTTPS
5. Request minimal scopes - Only request the permissions your app needs
6. Handle token expiration - Implement automatic token refresh
7. Revoke tokens on logout - Clean up when users disconnect your app

Error Handling

Common OAuth Errors

HTTP Status Codes

Support

For issues or questions about OAuth integration:

• Open an issue on GitHub
• See the API Guide for general API information
• Check the Swagger documentation for endpoint details