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. |
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.
The token endpoint is https://test.onslip360.com/v1/oauth-token.json for the testing sandbox or https://api.onslip360.com/v1/oauth-token.json for production. You must invoke this endpoint 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.
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.