Skip to main content
What you’ll learn:
  • How OAuth works with Metorial
  • Creating Provider Setup Sessions
  • Storing and reusing Provider Auth Configs
External resources:
OAuth lets your users authorize access to their accounts on services like Slack, GitHub, Google Calendar, and more. This enables your AI agents to perform actions on behalf of your users with their explicit permission.

​
How OAuth Works

The OAuth flow uses Provider Setup Sessions:
  1. Create a Provider Setup Session for the provider the user needs to authorize
  2. Redirect the user to the session URL to complete OAuth in their browser
  3. Wait for completion — returns the completed setup session with an auth config
  4. Store the Provider Auth Config ID for that user in your database
  5. Pass the auth config ID when creating sessions for that user

​
Creating Provider Setup Sessions

let setupSession = await metorial.providers.setupSessions.create({
    providerId: 'your-provider-id',
    providerAuthMethodId: 'oauth',

    // Optional: specify deployment if you have multiple for the same provider
    // providerDeploymentId: 'your-deployment-id',

    // Optional: redirect user here after authorizing
    // redirectUrl: 'https://yourapp.com/oauth/callback'
});

// Redirect your user to this URL
console.log('Authorize here:', setupSession.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 for this user
await db.users.update(userId, {
    slackAuthConfigId: completedSetup.authConfig.id
});

​
Using Auth Configs in Sessions

Retrieve the stored auth config ID from your database and pass it when creating a session: 
await metorial.withProviderSession(
    metorialAnthropic,
    {
        providers: [
            {
                providerDeploymentId: 'slack-deployment-id',
                providerAuthConfigId: storedAuthConfigId  // From your database
            }
        ]
    },
    async session => {
        // Tools now have access to user's Slack account
    }
);

​
Multiple OAuth Services

You can combine multiple OAuth-enabled providers in a single session: 
await metorial.withProviderSession(
    metorialAnthropic,
    {
        providers: [
            {
                providerDeploymentId: 'github-deployment-id',
                providerAuthConfigId: githubAuthConfigId
            },
            {
                providerDeploymentId: 'slack-deployment-id',
                providerAuthConfigId: slackAuthConfigId
            },
            {
                providerDeploymentId: 'exa-deployment-id'  // No OAuth needed
            }
        ]
    },
    async session => {
        // AI can now use GitHub, Slack, and Exa tools
    }
);

​
Complete Example

import { Metorial } from 'metorial';
import { metorialAnthropic } from '@metorial/anthropic';

let metorial = new Metorial({ apiKey: process.env.METORIAL_API_KEY });

// 1. Create setup session
let setupSession = await metorial.providers.setupSessions.create({
    providerId: 'your-slack-provider-id',
    providerAuthMethodId: 'oauth',
    redirectUrl: 'https://yourapp.com/oauth/callback'
});

// 2. Send URL to user
console.log('Please authorize:', setupSession.url);

// 3. Wait for completion
let completedSetup = await metorial.waitForSetupSession([setupSession]);

// 4. Store auth config ID for this user
// database.save(userId, completedSetup.authConfig.id)

// 5. Use in a session
await metorial.withProviderSession(
    metorialAnthropic,
    {
        providers: [
            {
                providerDeploymentId: 'your-slack-deployment-id',
                providerAuthConfigId: completedSetup.authConfig.id
            }
        ]
    },
    async session => {
        // Your AI now has access to user's Slack
    }
);

​
What’s Next?

Provider Examples

See how to use OAuth with different AI providers.

OAuth Integrations

Learn about OAuth-enabled integrations in the catalog.