Skip to content

docs(cdp): Add OAuth2 authentication to Custom REST source #18124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MarconLP merged 1 commit into from
Jul 3, 2026
Merged

docs(cdp): Add OAuth2 authentication to Custom REST source #18124

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 34 additions & 6 deletions contents/docs/cdp/sources/custom-rest-source.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,35 @@ The root URL that all stream paths are resolved against (e.g. `https://api.examp

Select an authentication type from the **Authentication** dropdown.

| Type | Fields | Description |
| ------------------- | ------------------------------------ | ------------------------------------------------------------------- |
| **No auth** | – | No authentication. Use for public APIs. |
| **Bearer token** | Token | Sends an `Authorization: Bearer <token>` header with every request. |
| **API key** | Location, Header/parameter name, Key | Sends the key as a header, query parameter, or cookie. |
| **HTTP basic auth** | Username, Password | Sends HTTP Basic credentials with every request. |
| Type | Fields | Description |
| ------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| **No auth** | – | No authentication. Use for public APIs. |
| **Bearer token** | Token | Sends an `Authorization: Bearer <token>` header with every request. |
| **API key** | Location, Header/parameter name, Key | Sends the key as a header, query parameter, or cookie. |
| **HTTP basic auth** | Username, Password | Sends HTTP Basic credentials with every request. |
| **OAuth2** | Client ID, Client secret, Token URL, Grant type, Refresh token (for `refresh_token` grant) | Authenticates via OAuth2. Supports `client_credentials` and `refresh_token` grants. |

Credentials are stored encrypted and never exposed in API responses.

#### OAuth2 configuration

OAuth2 authentication supports two grant types:

- **`client_credentials`** – Machine-to-machine authentication. The source exchanges the client ID and client secret for an access token. No user interaction is required.
- **`refresh_token`** – The source uses a pre-obtained refresh token (along with the client ID and secret) to mint access tokens. Use this for APIs where you've already completed an authorization flow outside PostHog.

The `authorization_code` grant is not supported.

| Field | Required | Description |
| ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client ID** | Yes | The OAuth2 client ID. |
| **Client secret** | Yes | The OAuth2 client secret. Stored encrypted and never returned in API responses. |
| **Token URL** | Yes | The endpoint PostHog calls to mint access tokens (e.g. `https://auth.example.com/oauth/token`). Cannot be changed after the source is created. |
| **Grant type** | Yes | `client_credentials` (default) or `refresh_token`. |
| **Refresh token** | For `refresh_token` grant | A pre-obtained refresh token. Required when using the `refresh_token` grant type. Stored encrypted and never returned. |
| **Scopes** | No | Space-separated OAuth2 scopes, if the provider requires them. |
| **Client auth method** | No | How credentials are sent to the token endpoint: `body` (form parameters, default) or `basic` (HTTP Basic). |

### Default headers

Optional key-value pairs sent with every request. Auth headers are added automatically based on your authentication configuration – you don't need to duplicate them here.
Expand Down Expand Up @@ -151,6 +171,14 @@ Common issues:

If using **Ascending** upstream row order (the default) and the API doesn't guarantee ascending order by the cursor field, rows can be skipped when a sync is interrupted and resumed. Set **Upstream row order** to **Descending** if the API returns newest records first.

### OAuth2 token errors

If an OAuth2 source's token expires or is revoked, the source fails with a `TOKEN_REFRESH_FAILED` error. To reconnect:

1. Edit the source settings.
2. Re-enter the **Client secret** and (for `refresh_token` grant sources) the **Refresh token**.
3. Save the source. PostHog validates the new credentials and clears the error once a token is successfully minted.

### Have a question? Ask PostHog AI

<AskAIInput placeholder="Ask about custom REST sources..." />
Loading