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:

Pathfix manages the OAuth connection and token lifecycle. Your application determines what API calls to make.

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:

Your application should use the third-party provider's official API documentation to determine:

Pathfix does not replace the provider's API.

Pathfix provides the authenticated transport between your application and that API.

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.

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:

The provider willnormally issue:

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.

In Pathfix:

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.

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:

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:

and uses the same value consistently for that end user.

The same user_id must be used when:

Do not generate a new user_id for individual connections or API requests.

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.

Then create the application's own Connect button and specify the Pathfix provider reference.

Example:

Replace:

with the application's Pathfix public key.

Replace:

with the currently authenticated application's stable user identifier.

Replace:

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.

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:

The provider and user ID must correspond to the same values used during authorization.

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:

Server-side requests can include:

using the credentials and format provided for the Pathfix Application.

The request body describes the provider API request:

For example, if the application needs Google Calendar events:

Pathfix will use the authorization belonging to the specified application user and provider.

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:

Keep the Pathfix private key in server-side environment variables or another secure secret store.

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:

Implementation reasoning should be:

Do not implement a separate Google OAuth system.

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.

When implementing Pathfix, follow these rules:



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.

For additional implementation details, use the relevant Pathfix documentation:

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.