Authentication and OAuth 2.0

As a developer on the Crunch platform, you have programmatic access to clients' data and resources, assuming they’ve authorised your application. To do this we provide an Oauth 2.0 implementation for authentication and authorisation, which is designed to allow your application to access the Crunch Accounting API whether the user is interacting with the application or not.

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. Source: https://oauth.net/2/

Note: By using the Crunch Accountancy API, you accept our Developer Terms of Service

1. Create Your application

To begin with you will need to obtain your Oauth 2 client credentials by creating a new application. While our API is in its initial beta phase we will onboard your new application to allow us to get a better understanding of how you plan to use the API. Please email api@crunch.co.uk with your name, company name, and a brief overview of what you’ll be using the API for, and we will help you get setup straight away

2. Obtain the access token

Before your application can access data using Crunch Accountancy API, it must obtain an access token that grants access to the API. The scope parameter used while requesting the access token controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

Obtaining the token requires an authentication step where the user logs in with their Crunch account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent.

If the user grants the permission, the Crunch Oauth API sends your application an authorisation code at the redirect url that you defined when setting up your application. This authorisation code can be exchanged to obtain the access token. If the user does not grant the permission, the server returns an error.

2.1: Prepare the authorisation request to obtain the authorisation code

The first step is to generate a url with all the parameters to identify your application, and the permissions (scopes) that the user will be asked to grant when they authorise your application. When the url is constructed you can redirect the user to that url to allow them to authorise your application. The url takes the following form:

GET https://oauth.crunch.co.uk/authorize

The following parameters are used with the authorize request:

Type Name Description Type
Query client_id
required
The client identifier. string
Query redirect_uri
required
The URL to which the browser will be redirected after authorization has been granted by the user. string
Query response_type
required
Use code for Authorization Code Grant Flow. string
Query scope
required
The scopes which you want to request authorization for. These must be separated by a space. Include offline_access to get a Refresh Token. Currently only all & offline_access are supported. string
Query state
required
RECOMMENDED. An opaque value used by the client to maintain state between the request and callback. This value must be used by the application to prevent CSRF attacks. string

Example:

https://oauth.crunch.co.uk/authorize?client_id=gf98we...78vyytc243&redirect_uri=https://my.app/integration/crunch&response_type=code&scope=all%20offline_access&state=k45oij652j

Should the user authorise your application to access their Crunch account they will be redirected to the url you specified in the redirect_uri url parameter with the authorisation code as a url parameter:

https://my.app/integration/crunch&code=eyJz93a...k4laUWw&state=k45oi...j652j

The code you receive is a short-lived token and should be exchanged for an access token straight away.

2.2: Swap the code for an access token

The next step is to use the code to obtain an access token. The access token will allow you to access the Crunch API. The code exchange is performed via the /token endpoint:

POST https://oauth.crunch.co.uk/token

The /token endpoint takes the following request payload for the code exchange and should use the application/x-www-form-urlencoded content type (as supplied by the Content-Type http header):

Name Description Type
client_id
required
The Client ID that was issued to the API User during signup.
Example : "gf98we...78vyytc243"
string
client_secret
required
The Client Secret provided by the API User on signup.
Example : "something-gr33n"
string
code
required
The Authorization Code received from the initial /authorize call. Required when grant_type is authorization_code only.
Example : "4kjh234...cviu9ads"
string
grant_type
required
Denotes the flow you are using. For Authorization Code, use authorization_code.
Example : "authorization_code"
enum (authorization_code, refresh_token)
redirect_uri
optional
This is required only if it was set at the GET /authorize endpoint. The values must match.
Example : "https://my.app/integration/crunch"
string

The /token endpoint returns a JSON object that contains a new access token. The following snippet shows a sample response:

{
  "access_token": "22deaca1-d19a-4591-aaae-f20ccbc2bb65",
  "token_type": "Bearer",
  "expires_in": 172800,
  "refresh_token": "63d3e15c-9601-4dcf-99bc-aeea70fd1f1f",
  "scope": "all offline_access"
}

The access token response payload is described below:

Name Description Type
access_token
required
The access token issued by the authorization server.
Example : "eyJz93a...k4laUWw"
string
expires_in
optional
The lifetime in seconds of the access token.
Example : 86400
integer (int64)
refresh_token
optional
The refresh token, which can be used to obtain new access tokens using the same authorization grant.
Example : "GEbRxBN...edjnXbL"
string
scope
optional
The permissions granted by the User. Optional if identical to the scope requested by the client.
Example : “all offline_access”
string
token_type
required
The type of the token issued. Value is case insensitive. At this time, this field will always have the value Bearer.
Example : "Bearer"
string

3. Refreshing the access token

Access tokens are valid for a period of time, after which you need to get a new one using the latest refresh_token returned to you from the previous request. You must write your code to anticipate the possibility that a granted access token might no longer work.

You only use the refresh token to obtain a new access token when the prior access token expires. Keep in mind that a refresh token is only for getting new (i.e., “refreshing”) access tokens; you can’t pass a refresh token when calling the Crunch API. You can refresh an access token without prompting the user for permission.

You refresh the access token by posting to the /token endpoint

POST https://oauth.crunch.co.uk/token

The /token endpoint takes the following request payload for the code exchange and should use the application/x-www-form-urlencoded content type (as supplied by the Content-Type http header):

Name Description Type
client_id
required
The Client ID that was issued to the API User during signup.
Example : "gf98we...78vyytc243"
string
client_secret
required
The Client Secret provided by the API User on signup.
Example : "something-gr33n"
string
grant_type
required
Denotes the flow you are using. To refresh the access token, use refresh_token.
Example : "refresh_token"
enum (authorization_code, refresh_token)
refresh_token
required
The refresh token previously issued to the API User. Required if grant_type is refresh_token.
Example : "GEbRxBN...edjnXbL"
string
scope
optional
The permissions granted by the User. Optional if identical to the scope requested by the client.
Example : “all offline_access”
string

The /token endpoint returns a JSON object that contains a new access token. The following snippet shows a sample response:

{
  "access_token": "22deaca1-d19a-4591-aaae-f20ccbc2bb65",
  "token_type": "Bearer",
  "expires_in": 172800,
  "refresh_token": "63d3e15c-9601-4dcf-99bc-aeea70fd1f1f",
  "scope": "all offline_access"
}

The access token response payload is described below:

Name Description Type
access_token
required
The access token issued by the authorization server.
Example : "eyJz93a...k4laUWw"
string
expires_in
optional
The lifetime in seconds of the access token.
Example : 86400
integer (int64)
refresh_token
optional
The refresh token, which can be used to obtain new access tokens using the same authorization grant.
Example : "GEbRxBN...edjnXbL"
string
scope
optional
The permissions granted by the User. Optional if identical to the scope requested by the client.
Example : “all offline_access”
string
token_type
required
The type of the token issued. Value is case insensitive. At this time, this field will always have the value Bearer.
Example : "Bearer"
string

4. Accessing the Crunch API

Now you have a valid access token you can use this to access the Crunch API. To do this you simply include the access token in the Authorization header with your API requests.

curl --location -g --request GET 'https://public-api.crunch.co.uk/expenses' \
--header 'MediaType: application/json' \
--header 'Authorization: <access_token>'