The Authorisation Flow

The process of authorising you application and getting access to the API is as follows:

  1. You direct your application to our authorisation endpoint to the user can grant permission for your application to authenticate with their Biggerplate account credentials
  2. Once permission is granted, take the Authorisation Code that is returned and make a call to our token endpoint to retrieve an Access Token
  3. 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:

ParameterDescription
client_idThe Client ID generated for your application
redirect_uriThe Redirect URI registered with your application.
response_typeMUST be set to "code".
stateOptional, 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_idThe Client ID generated for your application
client_secretThe Client Secret generated for your application
redirect_uriThis must be the same Redirect URI specified when retrieving your Authorisation Code
response_typeMust be token
codeValue returned when retrieving your Authorisation Code
grant_typeauthorization_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.