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.
Metorial only provides managed OAuth credentials for a subset of popular providers (e.g., Slack, GitHub). Other providers in the catalog may require you to register your own OAuth app and use Enterprise BYO. Check the provider’s page in the catalog to see which auth methods are available.
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:

​
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
In the dashboard, OAuth-based integration setup asks you to select or create auth credentials after you choose the provider auth method. For GitHub, the hosted OAuth option appears as GitHub.com; for Linear, it appears as OAuth. GitHub OAuth integration setup
Creating auth credentials starts a third-party authorization flow. Only continue when the user or account owner has approved connecting that GitHub, Linear, Slack, Google, or other third-party account.

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

setup_session = await metorial.providers.setup_sessions.create(
    provider_id="your-slack-provider-id",
    provider_auth_method_id="oauth",
    redirect_url="https://yourapp.com/oauth/callback"
)

# Redirect your user to this URL
print(f"Authorize here: {setup_session.url}")

curl -X POST https://api.metorial.com/provider-setup-sessions \
  -H "Authorization: Bearer metorial_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "prv_slack",
    "provider_auth_method_id": "pam_slack_oauth",
    "redirect_url": "https://yourapp.com/oauth/callback"
  }'
The response includes a url field—redirect your user to this 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 in your database
await db.users.update(userId, { slackAuthConfigId: completedSetup.authConfig.id });

# Waits until the user completes OAuth — returns the completed setup session
completed = await metorial.wait_for_setup_session(setup_session)

# Store the auth config ID in your database
await db.users.update(user_id, slack_auth_config_id=completed.auth_config.id)

curl https://api.metorial.com/provider-setup-sessions/pss_abc123 \
  -H "Authorization: Bearer metorial_sk_abc123"
StatusMeaning
pendingUser hasn’t completed the flow yet
completedUser authorized successfully—auth config is ready
expiredSession expired before the user completed it
failedAn error occurred during the flow
archivedSession 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. 
let session = await metorial.connect({
  adapter: metorialAnthropic(),
  providers: [
  	{
		providerDeploymentId: 'slack-deployment-id',
        providerAuthConfigId: storedAuthConfigId
    }
  ]
});

let tools = session.tools();

async with metorial.provider_session(
    provider="anthropic",
    providers=[
        {
            "provider_deployment_id": "slack-deployment-id",
            "provider_auth_config_id": stored_auth_config_id
        }
    ]
) as session:
    tools = session.tools

curl -X POST https://api.metorial.com/sessions \
  -H "Authorization: Bearer metorial_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": [
      {
        "provider_deployment_id": "pdp_slack",
        "provider_auth_config_id": "pac_xyz789"
      }
    ]
  }'

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