Setting Up OAuth Integrations

Use Provider Setup Sessions to authorize users with OAuth-based providers like Slack, GitHub, and Google.

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:

• Providers Guide
• SDK OAuth Guide
• Enterprise BYO

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.

TypeScript

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

TypeScript

// 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 });

Status	Meaning
pending	User hasn’t completed the flow yet
completed	User authorized successfully—auth config is ready
expired	Session expired before the user completed it
failed	An error occurred during the flow
archived	Session 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.

TypeScript

await metorial.withProviderSession(
    metorialAnthropic,
    {
        providers: [
            {
                providerDeploymentId: 'slack-deployment-id',
                providerAuthConfigId: storedAuthConfigId
            }
        ]
    },
    async session => {
        // Tools now have access to user's Slack
    }
);

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.