> ## Documentation Index
> Fetch the complete documentation index at: https://metorial.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Setting Up OAuth Integrations
> Use Provider Setup Sessions to authorize users with OAuth-based providers like Slack, GitHub, and Google.
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](/integrations-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:**
* [Providers Guide](/concepts-providers)
* [SDK OAuth Guide](/sdk-oauth)
* [Enterprise BYO](/integrations-enterprise-byo)
## 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**.
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.
```typescript TypeScript theme={null}
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);
```
```python Python theme={null}
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}")
```
```bash REST theme={null}
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
```typescript TypeScript theme={null}
// 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 });
```
```python Python theme={null}
# 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)
```
```bash REST theme={null}
curl https://api.metorial.com/provider-setup-sessions/pss_abc123 \
-H "Authorization: Bearer metorial_sk_abc123"
```
| Status | Meaning |
| ----------- | ------------------------------------------------- |
| `pending` | User hasn't completed the flow yet |
| `completed` | User authorized successfully—auth config is ready |
| `expired` | Session expired before the user completed it |
| `failed` | An error occurred during the flow |
| `archived` | Session 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.
```typescript TypeScript theme={null}
let session = await metorial.connect({
adapter: metorialAnthropic(),
providers: [
{
providerDeploymentId: 'slack-deployment-id',
providerAuthConfigId: storedAuthConfigId
}
]
});
let tools = session.tools();
```
```python Python theme={null}
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
```
```bash REST theme={null}
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:
```json theme={null}
{
"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](/integrations-enterprise-byo) for the setup steps.
## What's Next?
SDK documentation for handling OAuth flows.
Learn about the Metorial API.
Simpler integrations without OAuth.