---
title: Build user integrations with Pathfix
slug: ai
docTags:
createdAt: 2026-10-06T13:15:34.196Z
---
Pathfix is managed OAuth infrastructure for applications whose users need to connect third-party services such as Google, Microsoft, Slack, Salesforce, HubSpot, Xero, QuickBooks and hundreds of other providers.
Use Pathfix when you are building a feature where **users of the application need to connect their own third-party accounts**.
Examples:
- Let users connect their Google Calendar
- Connect a customer's HubSpot account
- Sync data with a user's Salesforce account
- Allow users to connect Slack
- Read or write data in a user's Xero account
Pathfix manages the OAuth connection and token lifecycle. Your application determines what API calls to make.
## Important: understand the architecture
When using Pathfix:
**Do not implement the provider OAuth flow yourself.**
**Do not store provider access tokens or refresh tokens in the application.**
**Do not implement provider token refresh logic.**
Pathfix manages authorization, access tokens, refresh tokens and the ongoing authenticated connection for each user.
When your application needs to call a third-party API, send the request through Pathfix. Pathfix applies the correct authentication for the connected user and forwards the request to the provider.
The architecture is:
:::BlockQuote
Application user
↓
Your application
↓
Pathfix
↓
Third-party API
:::
Your application should use the third-party provider's official API documentation to determine:
- API endpoints
- HTTP methods
- request parameters
- request bodies
- response formats
Pathfix does not replace the provider's API.
Pathfix provides the authenticated transport between your application and that API.
# Before writing code
The developer must have a Pathfix account and configure the provider they want their users to connect.
If the provider has not yet been configured, ask the developer to complete the following steps.
## 1. Create the OAuth application with the provider
The developer owns their OAuth application.
They must create an application in the third-party provider's developer console.
For OAuth providers, use this Pathfix redirect URI:
:::BlockQuote
https\://labs.pathfix.com/integrate/command
:::
The provider willnormally issue:
:::BlockQuote
Client ID
Client Secret
:::
Do not request that these credentials be added to the application's source code.
They should be entered directly into the developer's Pathfix provider configuration.
## 2. Configure the provider in Pathfix
In Pathfix:
1. Create or select the Pathfix Application.
2. Add the required provider.
3. Enter the provider Client ID and Client Secret.
4. Configure the required OAuth scopes.
5. Save the provider configuration.
6. Use Test Connection to verify the configuration.
The developer may need to enable the required APIs, scopes or permissions in the provider's developer console.
Refer to the provider's official developer documentation for these requirements.
# User identity
Every end-user connection in Pathfix is associated with a `user_id`.
The Pathfix parameter name is always `user_id`. Use `user_id `exactly as written everywhere Pathfix requires the application's end-user identifier. Do not use `userId`, `userid`, `userID`, or other variations. The value may be any identifier that uniquely references the end user, but the Pathfix parameter name must remain `user_id`. Use the same value consistently for that user across authorization, connection checks, API calls, and revocation.
The application must provide a user\_id that uniquely identifies the end user whose third-party account is being connected.
The value of user\_id can be any unique identifier used by the application, for example:
:::BlockQuote
user\_8f92a1
john\@example.com
customer\_12345
550e8400-e29b-41d4-a716-446655440000
:::
Pathfix does not prescribe the format or source of this identifier.
The only requirement is that the application sends it to Pathfix under the parameter name:
:::BlockQuote
user\_id
:::
and uses the same value consistently for that end user.
The same user\_id must be used when:
- authorizing a provider
- checking whether the provider is connected
- making authenticated provider API requests
- revoking or disconnecting the provider
Do not generate a new user\_id for individual connections or API requests.
# Connect a user
For code-based applications, Pathfix provides its OAuth helper library.
Load the Pathfix helper using the Pathfix application's public key and the authenticated application's user ID.
:::BlockQuote
\
:::
Then create the application's own Connect button and specify the Pathfix provider reference.
Example:
:::BlockQuote
\
:::
Replace:
:::BlockQuote
\[PATHFIX PUBLIC KEY]
:::
with the application's Pathfix public key.
Replace:
:::BlockQuote
\[END USER ID]
:::
with the currently authenticated application's stable user identifier.
Replace:
:::BlockQuote
googlecalendar
:::
with the Pathfix internal provider reference for the required integration.
The complete provider reference is available at:
https\://docs.pathfix.com/provider-reference
The application may completely customize the visual appearance of the Connect button.
Pathfix manages the authorization process after the user initiates the connection.
# Determine whether a user is connected
Applications should display the current connection state.
For server-based applications, prefer checking the connection through the server.
Pathfix also exposes connection state through its OAuth helper.
For example:
:::BlockQuote
$pinc.oauth.authorized(
"googlecalendar",
userId,
(authorized) => \{
console.log(authorized);
}
);
:::
The provider and user ID must correspond to the same values used during authorization.
# Make authenticated provider API calls
Once the user has connected the provider, authenticated API requests should go through Pathfix.
**Do not retrieve the provider OAuth token and make the authenticated request directly.**
Use the provider's official API documentation to determine the API endpoint, HTTP method, payload and required headers.
Then send that request through the Pathfix passthrough endpoint.
The endpoint format is:
:::BlockQuote
POST https\://labs.pathfix.com/oauth/method/\[PROVIDER]/call
:::
Server-side requests can include:
:::BlockQuote
user\_id
public\_key
private\_key
:::
using the credentials and format provided for the Pathfix Application.
The request body describes the provider API request:
:::BlockQuote
\{
"url": "\[PROVIDER API URL]",
"method": "\[HTTP METHOD]",
"payload": \{},
"headers": \{}
}
:::
For example, if the application needs Google Calendar events:
1. Consult the official Google Calendar API documentation.
2. Determine the appropriate Google Calendar endpoint and parameters.
3. Send that request through the Pathfix googlecalendar passthrough endpoint.
4. Return the provider response to the application.
Pathfix will use the authorization belonging to the specified application user and provider.
## Security rule
For modern code-based applications, authenticated Pathfix API requests that require the Pathfix private key should be made **server-side**.
Never expose the Pathfix private key in:
- browser JavaScript
- React client components
- public environment variables
- mobile client source
- frontend network requests
Keep the Pathfix private key in server-side environment variables or another secure secret store.
# Provider APIs
Pathfix does not define the functionality available from Google, Salesforce, HubSpot, Xero or other providers.
When implementing a feature, use the **provider's official API documentation**.
For example:
:::BlockQuote
User request:
"Show the next five events from the user's Google Calendar."
:::
Implementation reasoning should be:
:::BlockQuote
1\. User needs to connect a third-party account.
2\. Use Pathfix for Google authorization.
3\. Check that the application user has connected Google Calendar.
4\. Consult Google's official Calendar API documentation.
5\. Determine the correct Calendar endpoint and parameters.
6\. Send that API request through Pathfix passthrough.
7\. Use the returned Google response in the application.
:::
Do not implement a separate Google OAuth system.
# Disconnecting a provider
Applications should allow users to disconnect integrations.
Use Pathfix's revoke functionality for the relevant provider and application user.
Do not simply delete local application state while leaving the Pathfix connection active.
After revocation, update the application UI to show that the provider is disconnected.
# Rules for AI coding agents
When implementing Pathfix, follow these rules:
1. Use Pathfix when **users of the application** need to connect third-party accounts.
2. Do not confuse this with application authentication. Pathfix is not being used here to implement login to the application.
3. Do not implement provider OAuth authorization independently.
4. Do not store provider access tokens or refresh tokens.
5. Do not implement provider token-refresh logic.
6. Provide a unique identifier for the end user under the parameter name `user_id`
7. Keep the same Pathfix user ID throughout authorization, API calls, connection checking and revocation.
8. Send authenticated third-party API requests through Pathfix.
9. Keep the Pathfix private key server-side.
10. Use the third-party provider's official documentation for endpoints, methods, payloads and response formats.
11. Do not invent Pathfix provider reference names. Use the Pathfix Provider Reference documentation.
12. If Pathfix or the provider has not been configured, stop and tell the developer exactly which manual configuration step is required.
13. Never ask the developer to paste third-party Client Secrets into source code or chat when they can instead enter them directly into Pathfix.
14. Once the developer confirms configuration is complete, continue implementing the integration.
15. Always use `user_id` as the Pathfix end-user identifier parameter. Never rename it to match framework or JavaScript naming conventions.
If this guide does not provide a Pathfix endpoint or method for an operation, do not infer or construct one from conventional REST patterns. Use only endpoints and methods explicitly documented by Pathfix.
# Division of responsibility
### Pathfix manages
- End-user OAuth authorization
- Access tokens
- Refresh tokens
- Token refresh
- Token stamping
- Provider connection state
- Authenticated API passthrough
- Revocation/disconnection
### The application manages
- Application authentication
- Application users
- User interface
- Business logic
- Database
- Determining which provider API functionality is required
- Processing provider API responses
### The third-party provider defines
- API endpoints
- Request parameters
- Request payloads
- API response formats
- OAuth scopes and permissions
- Provider developer application requirements
# Existing Pathfix documentation
For additional implementation details, use the relevant Pathfix documentation:
- Getting started: https\://docs.pathfix.com/
- End-user authorization: https\://docs.pathfix.com/end-user-authorization
- Custom OAuth button: https\://docs.pathfix.com/creating-custom-oauth-button
- Pass-through API: https\://docs.pathfix.com/enable-pass-through-api
- Provider references: https\://docs.pathfix.com/provider-reference
- Pathfix keys: https\://docs.pathfix.com/pathfix-keys
When the existing documentation and this AI integration guide cover the same functionality, use the existing Pathfix API behavior. Do not invent unsupported Pathfix endpoints, SDK methods or authentication mechanisms.