Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mvriu5/forge/llms.txt

Use this file to discover all available pages before exploring further.

The Accounts API manages OAuth connections to external services like Google, GitHub, and Notion. These accounts enable widgets to access user data from integrated services.

​
Supported Providers

  • google - Google OAuth integration
  • github - GitHub OAuth integration
  • notion - Notion OAuth integration

​
Get Connected Accounts

Retrieve all connected OAuth accounts for the authenticated user. 
curl -X GET http://localhost:3000/api/accounts \
  -H "Cookie: session=your-session-token"

​
Response

Returns an array of connected account objects.
​
id
string
Unique account identifier
​
accountId
string
Provider-specific account ID
​
providerId
string
OAuth provider: google, github, or notion
​
userId
string
ID of the user who connected this account
​
accessToken
string | null
OAuth access token (sensitive - handle with care)
​
refreshToken
string | null
OAuth refresh token (sensitive - handle with care)
​
idToken
string | null
OpenID Connect ID token
​
accessTokenExpiresAt
string (ISO 8601) | null
Access token expiration timestamp
​
refreshTokenExpiresAt
string (ISO 8601) | null
Refresh token expiration timestamp
​
scope
string | null
OAuth scopes granted
​
createdAt
string (ISO 8601)
Account connection timestamp
​
updatedAt
string (ISO 8601)
Last update timestamp
[
  {
    "id": "acc_1234567890",
    "accountId": "google_user_id_xyz",
    "providerId": "google",
    "userId": "user123",
    "accessToken": "ya29.a0AfH6SMB...",
    "refreshToken": "1//0gLn8...",
    "idToken": null,
    "accessTokenExpiresAt": "2024-01-20T16:30:00.000Z",
    "refreshTokenExpiresAt": null,
    "scope": "https://www.googleapis.com/auth/userinfo.email",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T15:30:00.000Z"
  },
  {
    "id": "acc_0987654321",
    "accountId": "github_user_id_abc",
    "providerId": "github",
    "userId": "user123",
    "accessToken": "gho_16C7e42F292...",
    "refreshToken": "ghr_1B4a2e77...",
    "idToken": null,
    "accessTokenExpiresAt": "2024-01-21T10:30:00.000Z",
    "refreshTokenExpiresAt": "2024-07-15T10:30:00.000Z",
    "scope": "repo,user",
    "createdAt": "2024-01-16T12:00:00.000Z",
    "updatedAt": "2024-01-20T15:30:00.000Z"
  }
]
The response includes sensitive tokens. Never expose these in client-side code or logs.

​
Update Account

Update a connected account’s refresh token. 
curl -X PUT http://localhost:3000/api/accounts \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-token" \
  -d '{
    "provider": "google",
    "refreshToken": "1//0gLn8..."
  }'

​
Request Body

​
provider
string
required
OAuth provider: google, github, or notion
​
refreshToken
string
required
New refresh token for the account

​
Response

Returns the updated account object. 
{
  "id": "acc_1234567890",
  "accountId": "google_user_id_xyz",
  "providerId": "google",
  "userId": "user123",
  "accessToken": "ya29.a0AfH6SMB...",
  "refreshToken": "1//0gLn8...",
  "idToken": null,
  "accessTokenExpiresAt": "2024-01-20T16:30:00.000Z",
  "refreshTokenExpiresAt": null,
  "scope": "https://www.googleapis.com/auth/userinfo.email",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T16:00:00.000Z"
}

​
Delete Account

Disconnect an OAuth account. 
curl -X DELETE "http://localhost:3000/api/accounts?provider=google" \
  -H "Cookie: session=your-session-token"

​
Query Parameters

​
provider
string
required
OAuth provider to disconnect: google, github, or notion

​
Response

Returns the deleted account object. 
{
  "id": "acc_1234567890",
  "accountId": "google_user_id_xyz",
  "providerId": "google",
  "userId": "user123",
  "accessToken": "ya29.a0AfH6SMB...",
  "refreshToken": "1//0gLn8...",
  "idToken": null,
  "accessTokenExpiresAt": "2024-01-20T16:30:00.000Z",
  "refreshTokenExpiresAt": null,
  "scope": "https://www.googleapis.com/auth/userinfo.email",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T15:30:00.000Z"
}
Deleting an account will disconnect the OAuth integration and may break widgets that depend on it.

​
OAuth Flow

Connecting a new account typically follows this flow:
  1. Initiate OAuth - User clicks “Connect [Provider]” in the UI
  2. Redirect to Provider - User is redirected to the OAuth provider’s authorization page
  3. Authorization - User grants permissions
  4. Callback - Provider redirects back to Forge with authorization code
  5. Token Exchange - BetterAuth exchanges the code for access/refresh tokens
  6. Account Created - Account record is created in the database
  7. Widget Access - Widgets can now use the account to access provider APIs
This flow is handled automatically by BetterAuth. The Accounts API is primarily used to:
  • View connected accounts
  • Update refresh tokens when needed
  • Disconnect accounts

​
Token Refresh

Access tokens expire periodically. When a widget needs to use an expired token:
  1. Detect token expiration (check accessTokenExpiresAt)
  2. Use the refresh token to obtain a new access token
  3. Update the account using PUT /api/accounts
Most OAuth libraries handle this automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us