MetorialDocs

OAuth

Handle user authorization for OAuth-enabled providers using Provider Setup Sessions

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.providerDeployments.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
    // callbackUri: '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 sessions
let completed = await metorial.providerDeployments.setupSessions.waitForCompletion([setupSession]);

// Store the auth config ID for this user
await db.users.update(userId, {
    slackAuthConfigId: completed[0]!.authConfig!.id
});

Using auth configs in sessions

Retrieve the stored auth config ID from your database and pass it when creating a session:

let session = await metorial.connect({
  adapter: metorialAnthropic(),
  providers: [
    {
		providerDeploymentId: 'your-provider-deployment-id',
		providerAuthConfigId: storedAuthConfig
	}
  ]
});

Multiple OAuth services

You can combine multiple OAuth-enabled providers in a single session:

providers: [
  {
    providerDeploymentId: "github-deployment-id",
    providerAuthConfigId: githubAuthConfigId,
  },
  {
    providerDeploymentId: "slack-deployment-id",
    providerAuthConfigId: slackAuthConfigId,
  },
  {
    providerDeploymentId: "exa-deployment-id", // No OAuth needed
  },
]

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.providerDeployments.setupSessions.create({
    providerId: 'your-slack-provider-id',
    providerAuthMethodId: 'oauth',
    callbackUri: 'https://yourapp.com/oauth/callback'
});

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

// 3. Wait for completion
let completed = await metorial.providerDeployments.setupSessions.waitForCompletion([setupSession]);

// 4. Store auth config ID for this user
// database.save(userId, completed[0].authConfig.id)

// 5. Use in a session
let session = await metorial.connect({
  adapter: metorialAnthropic(),
  providers: [
    {
		providerDeploymentId: 'your-slack-provider-id',
		providerAuthConfigId: completed[0]!.authConfig!.id
	}
  ]
});