The Bipsync API supports the OAuth 2.0 standard for authorization. This enables applications to securely obtain access to data held in Bipsync.

Creating an OAuth Application

Before you can use OAuth, you will need to have an OAuth application created. This will involve Bipsync configuring a client ID and client secret for your application, as well as enabling the grant types and scopes that your application requires.

If you have access to the Bipsync Setup App you are able to register and manage OAuth Applications yourself.

🚧
Keep the client secret secure
Never expose the client secret publicly or to end users; it should be treated like a password.

There are two types of OAuth application that we can create:

A confidential application - this is for applications that can securely store the client secret, like a web application running on a server.
A public application - this is for applications that cannot securely store the client secret, like a native iOS or Andorid app.

Grant Types

Bipsync's OAuth implementation currently supports 3 OAuth Grant Types, with 2 variations of the Authorization Code Grant Type. Each of these is suitable for different use cases:

Grant Type	Description	Use Case
Authorization Code Grant	Obtain an access token to make requests on behalf of a user. Access tokens are scoped to a user.	A web or native app that authenticates with the API as a user and makes requests on behalf of that user.
Authorization Code Grant (Service Account)	Obtain an access token to make requests on behalf of a Service Account, rather than a named user.	A server-side integration or web app written by a Bipsync partner.
Refresh Token Grant	Exchange a refresh token for a new access token without requiring users to go through the authorization grant flow.	A web or native app that needs to obtain fresh access tokens on behalf of a user without using browser redirects.
Client Credentials Grant	Obtain an access token without user interaction. Access tokens are scoped to a team.	Machine-to-machine processes that do not make requests on behalf of a user.
Device Authorization Grant	Obtain an access token to make requests on behalf of a user. Access tokens are scoped to a user.	A device or process with no built-in browser or a device with limited input capability.

Passing Access Tokens to the API

When using an access token to make API requests, the value must be included in the Authorization HTTP header using the Bearer scheme. For example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY

The access token should not be quoted, encoded or altered in any way. See the OAuth specification for more details.

Error Handling

Bipsync follows the OAuth specification when it comes to error responses.

The OAuth 2.0 Simplified website covers the various error responses that can be produced.

Metadata

Bipsync supports the Authorization Server Metadata specification. This can be used for automated/programatic discovery of OAuth details, such as the authorization endpoint or token endpoint.

The endpoint is exposed at the standard well-known address, for example https://{client}-api.bipsync.com/.well-known/oauth-authorization-server