The Authorization Code Grant is best suited for applications that need to make API requests to Bipsync on behalf of a user. Access tokens will allow the bearer to access only the resources that a user has permission for.

An application can obtain an access token using the following flow:

Users are redirected to Bipsync to consent to access.
Users are redirected back to your application by Bipsync.
Your application obtains an access token and makes requests to the Bipsync API.

Redirect URIs

This Grant Type is built around redirecting users in their browser. In order to secure the process all redirect URIs must be registered with Bipsync. Attempting to use an unregistered redirect URI will result in an HTTP error being returned.

Redirect URIs must be absolute; relative URIs or wildcards are not supported. See the OAuth Specification for the full redirect URIs ruleset.

Authorization and Obtaining an Access Token

1. Generate a code challenge and verifier

Bipsync enforces uses of PKCE (Proof of Key Code Exchange) to prevent authorization code interception attacks. PKCE is an extension to the OAuth 2.0 framework and a requirement in the upcoming OAuth 2.1 specification.

Firstly you need to generate a code verifier. This is a cryptographically secure random string between 43 and 128 characters. Most languages and frameworks include methods to generate secure random strings.

The code verifier should be stored in short-lived session storage by the application. It will be required in step 4 when exchanging a code for an access token. The code verifier should never be exposed to users.

Once you have a code verifier, you will need to generate a code challenge. To generate the code challenge you will need to hash the code verifier using SHA-256. You will then need to encode the hash using base64url, a URL safe variant of base64.

The following code examples show how the code verifier and code challenge values can be generated:

import { createHash, randomBytes } from 'crypto';

const codeVerifier = randomBytes(64).toString('hex');
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');

from hashlib import sha256
from secrets import token_hex
from base64 import urlsafe_b64encode

codeVerifier=token_hex(64)
codeVerifierHash=sha256(codeVerifier.encode()).digest()
codeChallenge=urlsafe_b64encode(codeVerifierHash).decode("utf-8").rstrip("=")

2. Redirect to Bipsync

You will need to build a URI to redirect users to in their browser. This will begin with https://{client}.bipsync.com/oauth/authorize and include the following query string parameters:

Parameter name	Type	Description
`client_id`	`string`	Required. The client ID assigned to your application.
`redirect_uri`	`string`	Required. Must be a valid redirect URI assigned to your application.
`response_type`	`string`	Required. Use `code` as the value.
`code_challenge`	`string`	Required. The code challenge you generated in step 1.
`code_challenge_method`	`string`	Required. Use `S256` as the value.
`scope`	`string`	Optional. Space separated list of scopes. If this is left empty, then your access token will not be able to access API resources.
`state`	`string`	Optional. State that will be passed back to your application after redirecting.

Ensure that the query string parameters are correctly URL encoded.

If this is the first time the user has accessed your application or you are requesting additional scopes, the user will be prompted to consent.

3. Users are redirected back to your application

The user will be redirected back to the URI you specify in redirect_uri. If you provided a value for the state parameter, this will also be included in the query string.

If the user has consented, then the code query string parameter will be present. You should exchange this code for an access token.

ℹ️
The authorization code expires after 60 seconds
The authorization code must be exchanged for an access token within 60 seconds. If the code expires then the user will have to be redirected back to Bipsync to obtain a new code.

If the user has not consented or your request was not well formed, then the error query string parameter will be present. You should report this error to the user. Additional information may be included in the error_description and hint query string parameters.

4. Exchange code for an access token

To obtain an access token you need to make an HTTP request to POST https://{client}-api.bipsync.com/v1/oauth/token. You will need to include the following parameters in the request body encoded as form data or JSON:

Parameter name	Type	Description
`code`	`string`	Required. A short lived authorization code that can be exchanged for an access token.
`client_id`	`string`	Required. The client ID assigned to your application.
`redirect_uri`	`string`	Required The redirect URI that you used in the authorization request.
`grant_type`	`string`	Required. Use `authorization_code` as the value.
`code_verifier`	`string`	Required. The code verifier that you originally generated in step 1.
`client_secret`	`string`	Required for confidential clients The client secret assigned to your application.

For confidential clients the client_secret parameter is mandatory. Please ensure you make the request from a secure server-side process. For public clients the client_secret parameter must not be included in the request.

5. Handle the token response

If the request is successful you should receive an HTTP 200 status code and a JSON response in the following format:

{
  "token_type": "bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY...",
  "refresh_token": "def50200abf83399817830585462e876ade62cc3d07bc829582d4b4..."
}

The access_token contains a signed JSON Web Token. The access token expires after 60 minutes, at which point a new access token must be obtained.

The refresh_token can be used to obtain a new access token without prompting the user to redirect. It expires after 1 month.

🚧
Store the tokens securely
Access tokens and refresh tokens should be treated the same as passwords and stores securely.

Access Token Claims

The access token is a JWT which includes the following claims:

Claim	Type	Description
`sub`	`string`	The token subject. This is the ID of the user the token was issued to.
`scope`	`string`	Comma separated list of scopes.
`groups`	`array`	List of user group IDs that the user belongs to.

Obtaining Fresh Access Tokens

Redirecting users to Bipsync every time they need a token can be disruptive to workflows. The Refresh Token Grant can be used to avoid this.

The Refresh Token Grant allows a refresh token to be exchanged for a new access token without user interaction. For more details on implementing this, please see the Refresh Token Grant page.