Skip to main content
OAuth integrations require user authorization to access resources like Slack messages, GitHub repos, or Google Calendar events.
What you’ll learn:
  • Common OAuth patterns and use cases
  • How to handle OAuth for your users
  • OAuth export/import for reduced friction
  • Enterprise BYO (Bring Your Own) OAuth apps
Related resources:

​
OAuth Use Cases

​
One-Time User Authorization

The most common pattern: each user authorizes once, and you store their OAuth session for future use. How it works:
  1. User clicks “Connect” in your app
  2. They complete the OAuth flow (e.g., authorize Slack access)
  3. You store the oauthSessionId for that user
  4. Use that session ID for all future requests
// Create OAuth session (once per user)
let oauthSession = await metorial.oauth.sessions.create({
    serverDeploymentId: 'your-slack-deployment-id'
});

// Show user the authorization URL
console.log('Authorize here:', oauthSession.url);

// Wait for completion
await metorial.oauth.waitForCompletion([oauthSession]);

// Store oauthSession.id for this user in your database
await db.users.update(userId, { slackOAuthSessionId: oauthSession.id });

​
Enterprise BYO (Bring Your Own) OAuth Apps

For enterprise customers who want to use their own OAuth app credentials instead of Metorial’s. Why use BYO:
  • Use your company’s existing OAuth apps
  • Control branding in the OAuth consent screen
  • Comply with enterprise security policies
  • Manage OAuth credentials in your infrastructure
How it works: Create server deployments dynamically via the API with your own OAuth credentials. See the Server Deployment API for creating deployments programmatically with custom OAuth configurations.

​
OAuth Export/Import

For users who want to reduce friction or manage OAuth tokens outside of Metorial sessions.

​
Exporting OAuth Tokens

Export OAuth credentials for use in your own infrastructure: 
// Export OAuth session credentials
let credentials = await metorial.oauth.sessions.export(oauthSessionId);

​
Importing OAuth Tokens

Import existing OAuth tokens into Metorial: 
// Import existing OAuth credentials
let oauthSession = await metorial.oauth.sessions.import({
    serverDeploymentId: 'your-deployment-id',
    credentials: existingOAuthCredentials
});
This is useful when:
  • Migrating from another system
  • Users already have OAuth tokens from your app
  • You want to manage tokens in your own database

​
Using OAuth Sessions

Once a user is authorized, pass their OAuth session ID when creating MCP sessions: 
await metorial.withProviderSession(
    provider,
    {
        serverDeployments: [
            {
                serverDeploymentId: 'slack-deployment-id',
                oauthSessionId: storedOAuthSessionId // From your database
            }
        ]
    },
    async ({ tools, closeSession }) => {
        // Tools now have access to user's Slack
        await closeSession();
    }
);

​
What’s Next?

SDK OAuth Guide

Detailed SDK documentation for OAuth.

API Guide

Learn about the Metorial API.

API Key Integrations

Simpler integrations without OAuth.