OAuth Providers

PIE supports both built-in OAuth providers and custom OAuth 2.0 services.

Built-in Providers

These providers have pre-configured OAuth URLs. You only need to provide scopes and credentials.

Google

{
  "oauth": {
    "provider": "google",
    "scopes": [
      "https://www.googleapis.com/auth/gmail.readonly",
      "https://www.googleapis.com/auth/gmail.send"
    ],
    "clientIdSecret": "GOOGLE_CLIENT_ID",
    "clientSecretSecret": "GOOGLE_CLIENT_SECRET"
  }
}

Common Scopes:

Scope	Description
https://www.googleapis.com/auth/gmail.readonly	Read Gmail
https://www.googleapis.com/auth/gmail.send	Send emails
https://www.googleapis.com/auth/gmail.modify	Read and modify
https://www.googleapis.com/auth/drive.readonly	Read Drive files
https://www.googleapis.com/auth/calendar.readonly	Read Calendar
https://www.googleapis.com/auth/calendar.events	Manage events

Setup:

1. Go to Google Cloud Console
2. Create a new project or select existing
3. Enable the APIs you need (Gmail API, etc.)
4. Go to APIs & Services > Credentials
5. Create an OAuth 2.0 Client ID
6. Add authorized redirect URI: https://your-pie-domain.com/api/oauth/plugin/{pluginId}/callback

GitHub

{
  "oauth": {
    "provider": "github",
    "scopes": ["repo", "user"],
    "clientIdSecret": "GITHUB_CLIENT_ID",
    "clientSecretSecret": "GITHUB_CLIENT_SECRET"
  }
}

Common Scopes:

Scope	Description
repo	Full access to repositories
repo:status	Read/write commit status
public_repo	Public repos only
user	Read user profile
user:email	Read user email
read:org	Read org membership

Setup:

1. Go to GitHub Developer Settings
2. Click New OAuth App
3. Set callback URL: https://your-pie-domain.com/api/oauth/plugin/{pluginId}/callback

Slack

{
  "oauth": {
    "provider": "slack",
    "scopes": ["channels:read", "chat:write"],
    "clientIdSecret": "SLACK_CLIENT_ID",
    "clientSecretSecret": "SLACK_CLIENT_SECRET"
  }
}

Common Scopes:

Scope	Description
channels:read	View channels
channels:history	Read channel messages
chat:write	Send messages
users:read	View users
files:read	Access files

Setup:

1. Go to Slack API Apps
2. Click Create New App
3. Add OAuth scopes under OAuth & Permissions
4. Set redirect URL: https://your-pie-domain.com/api/oauth/plugin/{pluginId}/callback

Notion

{
  "oauth": {
    "provider": "notion",
    "scopes": [],
    "clientIdSecret": "NOTION_CLIENT_ID",
    "clientSecretSecret": "NOTION_CLIENT_SECRET"
  }
}

INFO

Notion doesn't use traditional scopes. Permissions are granted per-page by the user.

Setup:

1. Go to Notion Integrations
2. Click New Integration
3. Enable OAuth under Distribution
4. Set redirect URI: https://your-pie-domain.com/api/oauth/plugin/{pluginId}/callback

Custom Providers

For any OAuth 2.0 service not listed above:

{
  "oauth": {
    "provider": "custom",
    "providerName": "Dropbox",
    "authorizationUrl": "https://www.dropbox.com/oauth2/authorize",
    "tokenUrl": "https://api.dropboxapi.com/oauth2/token",
    "userInfoUrl": "https://api.dropboxapi.com/2/users/get_current_account",
    "revokeUrl": "https://api.dropboxapi.com/2/auth/token/revoke",
    "scopes": ["files.content.read", "files.content.write"],
    "clientIdSecret": "DROPBOX_CLIENT_ID",
    "clientSecretSecret": "DROPBOX_CLIENT_SECRET"
  }
}

Required Fields

Field	Description
provider	Must be "custom"
providerName	Display name for the service
authorizationUrl	OAuth authorization endpoint
tokenUrl	Token exchange endpoint
scopes	Array of scope strings
clientIdSecret	Key in developerSecrets for client ID
clientSecretSecret	Key in developerSecrets for client secret

Optional Fields

Field	Description
userInfoUrl	Endpoint to get user info (email, etc.)
revokeUrl	Token revocation endpoint

Redirect URI

When setting up your OAuth app, use this redirect URI pattern:

https://your-pie-domain.com/api/oauth/plugin/{pluginId}/callback

Where {pluginId} is your agent's UUID (available after creating the agent).

Security Best Practices

1. Never share credentials - Keep client secrets secure
2. Minimal scopes - Request only what you need
3. Handle revocation - Respect when users disconnect
4. Check connection - Always verify context.oauth.isConnected() first

Custom Provider Examples

Dropbox

{
  "oauth": {
    "provider": "custom",
    "providerName": "Dropbox",
    "authorizationUrl": "https://www.dropbox.com/oauth2/authorize",
    "tokenUrl": "https://api.dropboxapi.com/oauth2/token",
    "scopes": ["files.content.read"],
    "clientIdSecret": "DROPBOX_CLIENT_ID",
    "clientSecretSecret": "DROPBOX_CLIENT_SECRET"
  }
}

Spotify

{
  "oauth": {
    "provider": "custom",
    "providerName": "Spotify",
    "authorizationUrl": "https://accounts.spotify.com/authorize",
    "tokenUrl": "https://accounts.spotify.com/api/token",
    "userInfoUrl": "https://api.spotify.com/v1/me",
    "scopes": ["user-read-private", "user-read-email", "playlist-read-private"],
    "clientIdSecret": "SPOTIFY_CLIENT_ID",
    "clientSecretSecret": "SPOTIFY_CLIENT_SECRET"
  }
}

Linear

{
  "oauth": {
    "provider": "custom",
    "providerName": "Linear",
    "authorizationUrl": "https://linear.app/oauth/authorize",
    "tokenUrl": "https://api.linear.app/oauth/token",
    "scopes": ["read", "write"],
    "clientIdSecret": "LINEAR_CLIENT_ID",
    "clientSecretSecret": "LINEAR_CLIENT_SECRET"
  }
}