The Authorisation Flow
The process of authorising you application and getting access to the API is as follows:
- You direct your application to our authorisation endpoint to the user can grant permission for your application to authenticate with their Biggerplate account credentials
- Once permission is granted, take the Authorisation Code that is returned and make a call to our token endpoint to retrieve an Access Token
- Use the Access Token to make calls to the API
How to retrieve the Authorisation Code
Prerequisites
If you don't already have a Client ID and Client Secret then please consult our Registering an Application page
To get an Authorisation Code, direct your application to the following endpoint with the query parameters listed below:
https://accounts.biggerplate.com/oauth/auth
Required parameters:
| Parameter | Description |
|---|---|
| client_id | The Client ID generated for your application |
| redirect_uri | The Redirect URI registered with your application. |
| response_type | MUST be set to "code". |
| state | Optional, this value will be tracked throughout the OAuth flow in order to validate the origin of the request. |
Once the user clicks either Allow or Deny on the authorisation page, the accounts site will redirect the user back to the redirect_uri you specified with a code parameter or and error parameter.
If a code parameter is returned, the user has authorised your request and you can now swap the code for an access token.
Swapping your Authorisation Code for an Access Token
To swap the Authorisation Code for an access token, you need make a POST request to the following endpoint:
https://accounts.biggerplate.com/oauth/token
...containing the following parameters:
| client_id | The Client ID generated for your application |
| client_secret | The Client Secret generated for your application |
| redirect_uri | This must be the same Redirect URI specified when retrieving your Authorisation Code |
| response_type | Must be token |
| code | Value returned when retrieving your Authorisation Code |
| grant_type | authorization_code |
If authorisation is successful, you will get a **200 OK response with the following object:
{
"access_token": "SCLflnfYoplK260JxuzUKpXRtgoMxsg7oeCF7cV1",
"token_type": "Bearer",
"expires": 1441738946,
"expires_in": 3600,
"refresh_token": "bow0BsrGGF5feN2I7xVJ4gKaQ0TPzLMpKZi1K2Qx"
}
Congratulations
As long as all the information is correct, you will now have an access token to use with the API.
You should note that the access token as a TTL, usually 1 hour after which the access token will become void. You will have to use the refresh token to create a new access token that will last a further 1 hour.
See our Refreshing Access Tokens page.