> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentjam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom OAuth providers

> Connect to an OAuth provider that departs from the standard flow, or adjust a platform's flow.

Each [supported platform](https://docs.agentjam.com/accounts/oauth.md#supported-platforms) has its own connection function, and `oauthConnection()` connects [any other provider](https://docs.agentjam.com/accounts/oauth.md#other-providers) that follows standard OAuth 2.0 from its endpoints. For a provider that departs from the standard, pass `oauthConnection()` a `profile` that describes how to run its flow.

## Profile hooks

A profile is a set of hooks that the connection calls at each step of the flow. In Python, the names are snake\_case, such as `construct_authorize_params`.

| Hook | What it does |
| - | - |
| `endpoints` | The authorization, token, and revocation URLs |
| `pkce` | Whether to send a PKCE challenge and verifier |
| `defaultToken` | The token that receives scopes passed as a list, and that `credentials()` returns when no token name is given |
| `sharedTokens` | The tokens shared by every human who connects the same account, revoked once the last of those humans' grants ends |
| `constructAuthorizeParams` | The authorization URL's query parameters, built from the scopes requested for each token |
| `parseTokens` | Reads each named token, its granted scopes, and the account from a token response |
| `readError` | Reads why the provider refused a token request, including refusals sent with a successful status |
| `lostGrantErrors` | The error codes that mean the human revoked access or the grant expired. These end the tasks and schedules using the grant |
| `impliedScopes` | Maps a scope to the scopes it implies, so a grant that reports only the broader one still covers the narrower ones |
| `revokeTokens` | Revokes one of a grant's tokens with the provider, throwing if the provider refuses |
| `constructAccessUrl` | The provider's page where the human grants more access, which [`requireAccess()`](https://docs.agentjam.com/accounts/missing-access) links to by default |

## Adjust the standard profile

`constructStandardProfile()` builds the profile of a standard provider, which issues one token named `default`. It's exported from `@agentjam/sdk/oauth` (`agentjam.oauth` in Python), along with the types for writing hooks. Override the hooks where your provider differs:

```ts TypeScript theme={null}
import { oauthConnection } from "@agentjam/sdk";
import { constructStandardProfile } from "@agentjam/sdk/oauth";

const chat = oauthConnection({
  provider: "chat",
  scopes: ["chat:write"],
  clientId: process.env.CHAT_CLIENT_ID!,
  clientSecret: process.env.CHAT_CLIENT_SECRET!,
  redirectUri: "https://inbox.example.com/oauth/callback",
  store,
  profile: {
    ...constructStandardProfile({
      authorize: "https://chat.example.com/oauth/authorize",
      token: "https://chat.example.com/api/oauth.access",
    }),
    pkce: false,
    constructAuthorizeParams: ({ default: scopes = [] }) => ({
      scope: scopes.join(","),
    }),
    readError: (_response, body) =>
      body.ok === false ? { code: String(body.error) } : undefined,
  },
});
```

```python Python theme={null}
import os
from dataclasses import replace

import httpx

from agentjam import oauth_connection
from agentjam.oauth import OAuthEndpoints, TokenError, TokenResponse, construct_standard_profile


def construct_params(scopes: dict[str, list[str]]) -> dict[str, str]:
    return {"scope": ",".join(scopes.get("default", []))}


def read_error(response: httpx.Response, body: TokenResponse) -> TokenError | None:
    return TokenError(code=str(body["error"])) if body.get("ok") is False else None


standard = construct_standard_profile(
    OAuthEndpoints(
        authorize="https://chat.example.com/oauth/authorize",
        token="https://chat.example.com/api/oauth.access",
    )
)

chat = oauth_connection(
    provider="chat",
    scopes=["chat:write"],
    client_id=os.environ["CHAT_CLIENT_ID"],
    client_secret=os.environ["CHAT_CLIENT_SECRET"],
    redirect_uri="https://inbox.example.com/oauth/callback",
    store=store,
    profile=replace(
        standard,
        pkce=False,
        construct_authorize_params=construct_params,
        read_error=read_error,
    ),
)
```

For a provider whose token responses contain several nested tokens, `parseStandardToken()` (`parse_standard_token()` in Python) reads the standard fields of one token, so a custom `parseTokens` can call it once per token.

## Adjust a platform profile

Each platform's module also exports the profile its connection function uses, such as `slackProfile` from `@agentjam/sdk/slack` (`slack_profile` from `agentjam.slack` in Python). To change one of its hooks, copy the profile with your change, and pass the copy to `oauthConnection()` under the platform's provider name:

```ts TypeScript theme={null}
import { oauthConnection } from "@agentjam/sdk";
import { slackProfile } from "@agentjam/sdk/slack";

const slack = oauthConnection({
  provider: "slack",
  scopes: { bot: ["chat:write"] },
  clientId: process.env.SLACK_CLIENT_ID!,
  clientSecret: process.env.SLACK_CLIENT_SECRET!,
  redirectUri: process.env.SLACK_REDIRECT_URI!,
  store,
  profile: { ...slackProfile, pkce: true },
});
```

```python Python theme={null}
import os
from dataclasses import replace

from agentjam import oauth_connection
from agentjam.slack import slack_profile

slack = oauth_connection(
    provider="slack",
    scopes={"bot": ["chat:write"]},
    client_id=os.environ["SLACK_CLIENT_ID"],
    client_secret=os.environ["SLACK_CLIENT_SECRET"],
    redirect_uri=os.environ["SLACK_REDIRECT_URI"],
    store=store,
    profile=replace(slack_profile, pkce=True),
)
```

The other platforms export `googleProfile`, `githubProfile`, and `sentryProfile`. For a GitHub App, `constructGitHubAppProfile(slug)` (`construct_github_app_profile(slug)` in Python) builds the app's profile.

## Bring your own credentials

Any credential source, such as a credential vault, can stand in for `oauthConnection()` in a skill's `connections`. It implements the `CredentialSource` interface, whose methods include `authorize()`, which returns the link where the human connects their account, and `token()`, which returns a current access token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.