For security purposes the Crunch API implements the OAuth 1.0a protocol to control access to clients’ data and resources. This means that any application using the Crunch API must first authenticate itself with Crunch using this protocol.
We have included an overview of OAuth’s process below – you can find a more detailed explanation on their community site.
“OAuth provides a method for clients to access server resources on behalf of the resource owner (such as a different client or an end-user). It also provides a process for end-users to authorize third party-access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.” - OAuth 1.0 Protocol Specification
As the synopsis above highlights, the OAuth protocol provides a mechanism for resource owners (in the case of this API, the Crunch customer) to provide third-party applications with access to their Crunch protected data (e.g. their account’s information).
This access is granted without the third party having any access to the customer’s username and password and therefore the customer’s login details and security are not compromised in any way what-so-ever.
In order to facilitate access to these resources a series of requests and responses take place between the third-party application, Crunch and the Crunch customer (the resource owner). The OAuth authentication process is provided in the table below:
| Action | Description |
|---|---|
| The third-party application developer is given security credentials | Before a third party developer can start using the Crunch API they must first be given an API consumer key, and a shared secret string. These two pieces of information identify the third party developer (or consumer in OAuth terminology) to Crunch. It is possible to get an API consumer key, a shared secret, and a Crunch demo account by emailing api@crunch.co.uk. This is all you need to get your integration underway! |
| The third-party asks for some temporary credentials to use in the authorisation process | Once you have your API consumer key & shared secret it is possible to begin the authentication process. The initial request/response conversation that takes place is for the third-party app to use its consumer key & shared secret to get a temporary token to work with the Crunch server. The third-party application sends a HTTP POST request to the temporary credential’s end point with the required OAuth request parameters. The Crunch server will then check the credentials to confirm the third-party application’s identity, and also check that the callback URL of the API consumer account held by Crunch matches the callback URL parameter sent within the message. If all of these credentials match then a temporary token is returned to the third-party application. This temporary token is then used by the third-party application in every other authentication request/response with Crunch. |
| The third-party directs the Crunch customer to login to their Crunch account | Once a set of temporary credentials have been granted to the third-party application the next stage of authentication begins. At this point the resource owner (i.e. the Crunch customer) permissions the third party app to access their Crunch account data. This takes place by the third-party application redirecting the resource owner to a Crunch login URL, to enter their login details. The resource owner enters their login details into a site controlled by Crunch, and not a site controlled by the third-party application. This ensures that the resource owner’s username and password credentials are kept secret and not shared with any third-party. Once the resource owner authenticates themselves to Crunch by using their username and password, they are given the option to grant access to the third-party via form submission to Crunch. If the resource owner grants access to their data they are then redirected back to the third-party application by Crunch (or a verification code is displayed to the resource owner if the third-party application is using out of band callback). |
| The third-party then asks Crunch for an access token to use in all future conversations with Crunch | Once the third-party has been granted access to the Crunch client’s data the third-party must obtain an access token from Crunch. This access token is the token that is used when requesting any REST resource and is a long running token that identifies that the third-party is who they say they are, and also has been granted access by the resource owner. Once Crunch returns the access token to the third-party, they are considered authenticated. |
The three authorisation URLs required to then access Crunch are:
To be authorised to use the live Crunch API you will need to send an email to api@crunch.co.uk with your name, company name and a brief overview of what you’ll be using the API for.