Skip to main content
OAuth integrations let users authorize access to their personal accounts—like Slack workspaces, GitHub repos, or Google Calendars—so your AI can perform actions on their behalf.
What you’ll learn:
  • How to create a Provider Setup Session to authorize a user
  • How to store and reuse Provider Auth Configs
  • Advanced patterns (BYO OAuth)
Related resources:

​
The OAuth Flow

Each user authorizes once. You store their Provider Auth Config ID in your database and reuse it for future sessions. The flow:
  1. Create a Provider Setup Session for the provider
  2. Redirect your user to the session URL to complete OAuth
  3. Poll or webhook until the session status is completed
  4. Store the resulting Provider Auth Config ID for that user
  5. Pass the auth config ID when creating sessions for that user

​
Creating a Provider Setup Session

Create a setup session specifying the provider, auth method, and optionally a redirect URL to send the user back to after they authorize. 
let setupSession = await metorial.providers.setupSessions.create({
    providerId: 'your-slack-provider-id',
    providerAuthMethodId: 'oauth',
    redirectUrl: 'https://yourapp.com/oauth/callback'
});

// Redirect your user to this URL
console.log('Authorize here:', setupSession.url);
The response includes a url field—redirect your user to this URL.

​
Waiting for Completion

// Waits until the user completes OAuth — returns the completed setup session
let completedSetup = await metorial.waitForSetupSession([setupSession]);

// Store the auth config ID in your database
await db.users.update(userId, { slackAuthConfigId: completedSetup.authConfig.id });
StatusMeaning
pendingUser hasn’t completed the flow yet
completedUser authorized successfully—auth config is ready
expiredSession expired before the user completed it
failedAn error occurred during the flow
archivedSession was manually deleted

​
Using an Auth Config in Sessions

Pass the stored Provider Auth Config ID when creating a session. Metorial uses it to authenticate tool calls on behalf of the user. 
let session = await metorial.connect({
  adapter: metorialAnthropic(),
  providers: [
  	{
		providerDeploymentId: 'slack-deployment-id',
        providerAuthConfigId: storedAuthConfigId
    }
  ]
});

let tools = session.tools();

​
Multiple OAuth Providers

You can attach multiple providers—each with their own auth config—to a single session: 
{
  "providers": [
    {
      "provider_deployment_id": "pdp_github",
      "provider_auth_config_id": "pac_github_user123"
    },
    {
      "provider_deployment_id": "pdp_slack",
      "provider_auth_config_id": "pac_slack_user123"
    },
    {
      "provider_deployment_id": "pdp_exa"
    }
  ]
}
API key-based providers (like Exa) don’t need an auth config—their credentials are stored at the deployment level.

​
Advanced Features

​
Enterprise BYO (Bring Your Own) OAuth

Need OAuth consent screens to show your company name? You can register your own OAuth app with the provider (GitHub, Slack, Google, etc.) and create a provider deployment that uses your credentials instead of Metorial’s defaults. See Enterprise BYO for the setup steps.

​
What’s Next?

SDK OAuth Guide

SDK documentation for handling OAuth flows.

API Guide

Learn about the Metorial API.

API Key Integrations

Simpler integrations without OAuth.