OAuth Authorization Code Flow

In order to reduce onboarding friction when a user enables your integration, you should use the OAuth 2.0 Authorization Code Flow. The user is first redirected from your own web site to the Onslip 360 Backoffice site in order to authorize and configure the integration, and then redirected back with an authorization code that you can exchange for an actual API access token.

Here is how it works. For more information about OAuth 2.0, please refer to The OAuth 2.0 Authorization Framework or OAuth 2.0 Simplified. We use the Authorization Code Flow with the PKCE extension.

Register your integration

First, you need to register your integration by adding an Integration entity to the integrations list. This describes your integration, helps customers find out more and defines what permissions or feature flags are required to use it.

Initially, the integration will only be available to users in your own account. Please contact us at api@onslip.com when you are ready to make it public for all Onslip 360 users.

Redirect to our authorization endpoint

The authorization endpoint is https://test.onslip360.com/oauth-authorization for the testing sandbox or https://www.onslip360.com/oauth-authorization for production. You should append the following query parameters and make your user open the resulting URL in a web browser.

Query Parameter	Required	Description
client_id	Yes	The alias of the integration to activate.
code_challenge_method	Yes	Must be set to S256.
code_challenge	Yes	The PKCE code challenge.
redirect_uri	Yes	Where the user should be redirected back to once the integration has been authorized.
response_type	Yes	Must be set to code.
scope	No	If you'd like to ask for fewer permissions than specified when you registered the integration, pass a space-separated list of permissions here.
state	No	A custom value that will be passed back to you via a query parameter in the redirect_uri callback endpoint.

tip

If you use one of the SDKs we provide, you can use the oauthPKCE() utility function to generate a fresh code_challenge/code_verifier key pair.

If the user grants access, an authorization code will be returned back to you via the code query parameter of the redirect_uri callback endpoint. Otherwise, information about what went wrong will be provided via the error and error_description query parameter.

Retrieve the Access Token

Finally, you will need to exchange the authorization code for an access token that you can use to make API requests. This is done via the requestOAuthAccessToken endpoint and you must do so within 60 seconds, or else the authorization code will expire.

Then plug the access_token value as Key identifier and secret as Key into your Hawk library as previously described and you are ready to go.

note

Our SDKs expect the Hawk key to be Base 64-encoded (since most other keys are fully binary) so don't forget to encode the key before passing it to your preferred SDK.