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
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
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.
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.
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 |
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 |
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>'