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:
  • Setting up OAuth for your users
  • Managing OAuth sessions
  • Advanced patterns (BYO OAuth, export/import)
Related resources:

​
Basic OAuth Setup

Each user authorizes once, you store their OAuth session ID in your database, then reuse it for future requests. The flow:
  1. User clicks “Connect Slack” (or GitHub, Google, etc.) in your app
  2. They authorize access via the OAuth screen
  3. You receive an oauthSessionId and store it for that user
  4. Pass that session ID whenever creating MCP sessions for that user
// 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 });

​
Using OAuth Sessions

After a user authorizes, retrieve their stored OAuth session ID from your database and pass it when creating MCP sessions. This connects the session to their authorized account, giving your AI access to their data. 
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();
    }
);

​
Advanced Features

​
Enterprise BYO (Bring Your Own) OAuth

Need to use your own OAuth apps instead of Metorial’s? Create server deployments via the API with your own credentials.
Why use BYO OAuth:
  • OAuth consent screens show your company name
  • Use existing OAuth apps from your organization
  • Meet enterprise security and compliance requirements
  • Full control over OAuth scopes and permissions
How it works: Call the Server Deployment API with your OAuth app credentials (client ID, client secret) to create a custom deployment. Users authorize via your OAuth app, and you use the deployment like any other. See Enterprise BYO for detailed setup instructions.

​
OAuth Export/Import

Manage OAuth tokens outside of Metorial or migrate from existing systems. Exporting tokens: Extract OAuth credentials from Metorial sessions for use in your own infrastructure, migration to another system, or backup purposes. 
// Export OAuth session credentials
let credentials = await metorial.oauth.sessions.export(oauthSessionId);
Importing tokens: Import existing OAuth tokens into Metorial instead of asking users to re-authorize. Useful when migrating from another system or if users already have OAuth tokens from your app. 
// Import existing OAuth credentials
let oauthSession = await metorial.oauth.sessions.import({
    serverDeploymentId: 'your-deployment-id',
    credentials: existingOAuthCredentials
});

​
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.