OAuth Credentials

As part of a partner's onboarding with Bipsync, OAuth credentials will be supplied to give access to the Bipsync API. Generally two types of credentials will be supplied:

• Sandbox credentials - for use during development.
• Production credentials - for accessing client's data.

These credentials will consist of a Client ID and a Client Secret. The Client Secret must be stored securely and not made visible to clients.

The Redirect URLs will need to be supplied to Bipsync in order for OAuth credentials to be generated.

Authorization Flow and Access Scenarios

The OAuth Authorization Code Grant is used to obtain an initial access and refresh token pair. This works as follows:

sequenceDiagram
  Client->>Bipsync: Requests integration to be enabled.
  Bipsync->>Client: CS team enables integration via Setup App and informs client.
  Client->>Partner: Clicks "Authenticate with Bipsync" in partner system.
  Partner->>Bipsync: Redirects to the Bipsync web app for the user to authorize access.
  Bipsync->>Client: Displays a confirmation of what the partner will have access to.
  Client->>Bipsync: Authorizes or declines the request
  Bipsync->>Partner: Returns access token
  Partner->>Bipsync: Uses access token to make API requests

The access and refresh tokens needs to be stored securely. The Refresh Token Grant can be used to acquire further access tokens without user input.

There are two scenarios for API authentication. The solution depends on the access needs of the partner application:

Service Accounts

A service account allows Bipsync to treat a partner app as a user, enabling appropriate sharing and ownership of documents created or modified through the app.

When an OAuth app is configured to use a service account, all actions performed through the app are executed on behalf of the service account, not the individual user who authorized the app.

For example, if a partner app creates a document via the API, that document will be authored and owned by the service account, not the user. Standard sharing and access controls apply, just as they would for any regular user account.

Authorization Flow

This flow uses the Authorization Code Grant. It allows an access token to be issued to a service account, rather than a named user:

sequenceDiagram
  participant Partner as Partner
  participant Bipsync as Bipsync

  Partner ->>+ Bipsync: 1. Redirect to /oauth/authorization
  Bipsync ->> Bipsync: 2. Verify authenticated user can install service account apps.
  Bipsync ->> Bipsync: 3. Authorization prompt shown to user with Approve / Deny actions*.
  Bipsync ->>- Partner: 4. Return authorization code
  Partner ->>+ Bipsync: 5. POST /v1/oauth/token
  Bipsync ->> Bipsync: 6. Create service account if one doesn't exist already.
  Bipsync ->>- Partner: 7. Access token issued to service account
  Partner ->>+ Bipsync: 8. API requests with access token

*Only privileged Bipsync users (Admin Users) are permitted to install partner apps that require a service account.

Migrating from API Tokens

If you already have an integration with Bipsync that uses API Tokens, this can be migrated to use OAuth as follows:

1. Obtain OAuth credentials from Bipsync. Redirect URL(s) will need to be supplied.
2. Modify your integration code so that it leverages the Authorization Code Grant to get an initial access token, and the Refresh Token Grant Type to obtain subsequent tokens.
3. Confirm which Bipsync clients need to have the OAuth application enabled.
4. Provide a means for clients who are already onboarded with your integration to re-authenticate using OAuth.