OAuth2
Documentation for OAuth2
Base path: /api/v1/oauth2
Handles the OAuth2 authorization code flow for connecting third-party integrations. The frontend initiates the flow by redirecting to the authorize endpoint, and the integration service handles the callback.
OAuth2 Flow Overview
GET /api/v1/oauth2/:group/authorize
Initiates an OAuth2 authorization flow. The server constructs the provider's authorization URL and redirects the user to it.
Authentication
Requires JWT (authMiddleware + activeOrgPreferenceMiddleware).
Path Parameters
| Parameter | Type | Description |
|---|---|---|
group | string | Integration group/slug (e.g. "google-workspace", "slack") |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
appCallbackUrl | string (URL) | Yes | URL to redirect to after successful auth (your frontend callback URL) |
action | string | Yes | The specific action to authorize, or "all" for all actions |
scopes | string[] | No | Additional OAuth2 scopes to request (space or comma-separated, or multiple params) |
token | string | No | Override JWT token (useful when redirect carries the token) |
baseUrl | string | No | Custom base URL for self-hosted service instances |
Response
302 Found — Redirects the browser to the OAuth2 provider's authorization URL.
The redirect URL includes:
- A
stateparameter encoding{ appCallbackUrl, userId, orgKey, action, scopes, baseUrl } - The
redirect_uripointing to the callback endpoint - Requested scopes
- PKCE parameters (if required by the integration)
Example
GET /api/v1/oauth2/:group/callback
Handles the OAuth2 provider's callback after the user authorizes the application. Exchanges the authorization code for access/refresh tokens and stores them.
Authentication
No authentication required. This endpoint is called by the OAuth2 provider's redirect.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
group | string | Integration group/slug |
Query Parameters (provided by the OAuth2 provider)
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Authorization code from the OAuth2 provider |
state | string | Yes | State parameter (contains encoded callback URL and context) |
Response
302 Found — Redirects to the appCallbackUrl with a status parameter:
https://myapp.example.com/oauth/callback?status=success
On error, the redirect may include an error parameter:
https://myapp.example.com/oauth/callback?status=error&error=access_denied
Frontend Callback Handling
Integration-Specific Notes
PKCE Support
Some integrations require PKCE (Proof Key for Code Exchange). When requiresPKCE: true is set in the integration's credential configuration, the server automatically handles PKCE challenge/verifier generation and validation.
Custom Base URLs
For self-hosted service instances (e.g. self-hosted GitLab, Jira), pass the baseUrl parameter to override the default API base URL used for token exchange.
Scope Handling
The OAuth2 scopes are determined by the action's scopes configuration. The scopes query parameter allows requesting additional scopes beyond the action's defaults. Multiple scopes values can be passed as an array or comma-separated string.
Token Storage
After successful exchange:
- Access tokens and refresh tokens are encrypted and stored in the integration service database
- Tokens are scoped to
(userId, orgKey, integrationSlug, action) - Refresh is handled automatically when tokens expire