{"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"}