{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Authorisation","type":"basic","slug":"authorization-flow","excerpt":"","body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"The Authorisation Flow\"\n}\n[/block]\nThe process of authorising you application and getting access to the API is as follows:\n\n1. You direct your application to our *authorisation endpoint* to the user can grant permission for your application to authenticate with their Biggerplate account credentials\n2. Once permission is granted, take the Authorisation Code that is returned and make a call to our *token endpoint* to retrieve an *Access Token*\n3. Use the Access Token to make calls to the API\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How to retrieve the Authorisation Code\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"If you don't already have a **Client ID** and **Client Secret** then please consult our [Registering an Application](/docs/register-your-application) page\",\n  \"title\": \"Prerequisites\"\n}\n[/block]\nTo get an Authorisation Code, direct your application to the following endpoint with the query parameters listed below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://accounts.biggerplate.com/oauth/auth\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nRequired parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"client_id\",\n    \"0-1\": \"The **Client ID** generated for your application\",\n    \"1-0\": \"redirect_uri\",\n    \"1-1\": \"The **Redirect URI** registered with your application.\",\n    \"2-1\": \"MUST be set to \\\"code\\\".\",\n    \"2-0\": \"response_type\",\n    \"3-0\": \"state\",\n    \"3-1\": \"Optional, this value will be tracked throughout the OAuth flow in order to validate the origin of the request.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nOnce 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.\n\nIf a **code** parameter is returned, the user has authorised your request and you can now swap the code for an access token.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Swapping your Authorisation Code for an Access Token\"\n}\n[/block]\nTo swap the *Authorisation Code* for an access token, you need make a **POST** request to the following endpoint:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://accounts.biggerplate.com/oauth/token\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n...containing the following parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"client_id\",\n    \"0-1\": \"The **Client ID** generated for your application\",\n    \"1-0\": \"client_secret\",\n    \"1-1\": \"The **Client Secret** generated for your application\",\n    \"2-0\": \"redirect_uri\",\n    \"2-1\": \"This must be the same **Redirect URI** specified when retrieving your Authorisation Code\",\n    \"3-0\": \"response_type\",\n    \"3-1\": \"Must be **token**\",\n    \"4-0\": \"code\",\n    \"4-1\": \"Value returned when retrieving your Authorisation Code\",\n    \"5-0\": \"grant_type\",\n    \"5-1\": \"authorization_code\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\nIf authorisation is successful, you will get a **200 OK response with the following object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"access_token\\\":  \\\"SCLflnfYoplK260JxuzUKpXRtgoMxsg7oeCF7cV1\\\",\\n  \\\"token_type\\\":    \\\"Bearer\\\",\\n  \\\"expires\\\":       1441738946,\\n  \\\"expires_in\\\":    3600,\\n  \\\"refresh_token\\\": \\\"bow0BsrGGF5feN2I7xVJ4gKaQ0TPzLMpKZi1K2Qx\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Congratulations\",\n  \"body\": \"As long as all the information is correct, you will now have an *access token* to use with the API.\"\n}\n[/block]\nYou 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.\n\nSee our [Refreshing Access Tokens](doc:refresh-tokens) page.","updates":["570e39b87e5c9f0e00bf1130"],"order":2,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"55eee9856ec7282b00e3028e","__v":24,"category":{"sync":{"isSync":false,"url":""},"pages":["55eedd1c08f9423700896e6b","55eee2786af7743700e57ee6","55ef3df27c751f0d007ff82e","55ef619ca3a8021700a4983b"],"title":"Getting started","slug":"getting-started","order":0,"from_sync":false,"reference":false,"_id":"55eedd1b08f9423700896e69","project":"55eedd1a08f9423700896e65","createdAt":"2015-09-08T13:05:31.554Z","version":"55eedd1b08f9423700896e68","__v":4},"project":"55eedd1a08f9423700896e65","createdAt":"2015-09-08T13:58:29.047Z","githubsync":"","version":{"version":"1.0","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":true,"is_hidden":false,"is_deprecated":false,"categories":["55eedd1b08f9423700896e69","55eedf54d6e2c62b001ac0f5","55eedf63b97ce63700d0592a","55ef11c0c2c70e23001077ec","55ef1ac37c751f0d007ff7d3","55ef1ae78eb7ae0d00feeb5d","55ef1b44e7f5490d000c0e38","55ef1b552eaf2917007d6b46","55ef40ed7c751f0d007ff839","55f0391f8563861700a33771","55fb3d4aa62ba1170021aa20"],"_id":"55eedd1b08f9423700896e68","project":"55eedd1a08f9423700896e65","createdAt":"2015-09-08T13:05:31.033Z","releaseDate":"2015-09-08T13:05:31.033Z","__v":11},"user":"55eedd0b08f9423700896e64"}

Getting started

Maps API

Users API

Categories API

Software API

Stay Connected

Authorisation

[block:api-header] { "type": "basic", "title": "The Authorisation Flow" } [/block] 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 [block:api-header] { "type": "basic", "title": "How to retrieve the Authorisation Code" } [/block] [block:callout] { "type": "warning", "body": "If you don't already have a **Client ID** and **Client Secret** then please consult our [Registering an Application](/docs/register-your-application) page", "title": "Prerequisites" } [/block] To get an Authorisation Code, direct your application to the following endpoint with the query parameters listed below: [block:code] { "codes": [ { "code": "https://accounts.biggerplate.com/oauth/auth", "language": "text" } ] } [/block] Required parameters: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Description", "0-0": "client_id", "0-1": "The **Client ID** generated for your application", "1-0": "redirect_uri", "1-1": "The **Redirect URI** registered with your application.", "2-1": "MUST be set to \"code\".", "2-0": "response_type", "3-0": "state", "3-1": "Optional, this value will be tracked throughout the OAuth flow in order to validate the origin of the request." }, "cols": 2, "rows": 4 } [/block] 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. [block:api-header] { "type": "basic", "title": "Swapping your Authorisation Code for an Access Token" } [/block] To swap the *Authorisation Code* for an access token, you need make a **POST** request to the following endpoint: [block:code] { "codes": [ { "code": "https://accounts.biggerplate.com/oauth/token", "language": "text" } ] } [/block] ...containing the following parameters: [block:parameters] { "data": { "0-0": "client_id", "0-1": "The **Client ID** generated for your application", "1-0": "client_secret", "1-1": "The **Client Secret** generated for your application", "2-0": "redirect_uri", "2-1": "This must be the same **Redirect URI** specified when retrieving your Authorisation Code", "3-0": "response_type", "3-1": "Must be **token**", "4-0": "code", "4-1": "Value returned when retrieving your Authorisation Code", "5-0": "grant_type", "5-1": "authorization_code" }, "cols": 2, "rows": 6 } [/block] If authorisation is successful, you will get a **200 OK response with the following object: [block:code] { "codes": [ { "code": "{\n \"access_token\": \"SCLflnfYoplK260JxuzUKpXRtgoMxsg7oeCF7cV1\",\n \"token_type\": \"Bearer\",\n \"expires\": 1441738946,\n \"expires_in\": 3600,\n \"refresh_token\": \"bow0BsrGGF5feN2I7xVJ4gKaQ0TPzLMpKZi1K2Qx\"\n}", "language": "json" } ] } [/block] [block:callout] { "type": "success", "title": "Congratulations", "body": "As long as all the information is correct, you will now have an *access token* to use with the API." } [/block] 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](doc:refresh-tokens) page.