{"__v":20,"_id":"55b67c106127b125003644cc","category":{"__v":1,"_id":"55b67be9c2e909190073ed38","pages":["55b67c106127b125003644cc"],"project":"5564f26a1fd04c0d00dc9aaa","version":"5564f26a1fd04c0d00dc9aad","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-27T18:43:53.629Z","from_sync":false,"order":5,"slug":"authentication","title":"Authentication"},"parentDoc":null,"project":"5564f26a1fd04c0d00dc9aaa","user":"5564f227f0f70f0d00a9ab20","version":{"__v":15,"_id":"5564f26a1fd04c0d00dc9aad","project":"5564f26a1fd04c0d00dc9aaa","createdAt":"2015-05-26T22:23:38.671Z","releaseDate":"2015-05-26T22:23:38.671Z","categories":["5564f26b1fd04c0d00dc9aae","556741d17acd550d0075eaca","556741d87acd550d0075eacb","556742f87acd550d0075ead1","556781cd6976ef0d0099c545","5568d666d33aad0d00ec8d2e","557f6b2d38249b0d00d0d12b","55b67be9c2e909190073ed38","564e56c601e80e0d00396684","56731b714b2a680d00524daf","573612ac652bd80e00a90027","57365e2cf8ebd31700769f50","57366131f8ebd31700769f58","573b93514e029d19000b8669","573bbfdb7ac6f6170033bd35"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-07-27T18:44:32.087Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Started\"\n}\n[/block]\nOAuth allows your application to make authenticated requests on behalf of a user.\n\nYou will need to register your application with Octoblu to get started.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example Server\"\n}\n[/block]\nCheckout [octoblu/octoblu-oauth-server-example](https://github.com/octoblu/octoblu-oauth-server-example) for a working example using Octoblu OAuth.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Register an Application\"\n}\n[/block]\nTo register a new OAuth application with Octoblu, first you will create an OAuth device.\n\nVisit the [Things](https://app.octoblu.com/node-wizard) page to add a new Thing. Select `OAuth Application`.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/qzMOjpjPT22RuhgkG3Ie_Screenshot%202015-07-27%2011.59.32.png\",\n        \"Screenshot 2015-07-27 11.59.32.png\",\n        \"2432\",\n        \"2182\",\n        \"#14538b\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nGive your OAuth Application a name, this is for your reference and will not be shown to your users.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/hTCefcv7QPGR2MwnPVcP_Screenshot%202015-07-27%2012.00.42.png\",\n        \"Screenshot 2015-07-27 12.00.42.png\",\n        \"2426\",\n        \"2186\",\n        \"#14548b\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nFill in the properties. `name` and `imageUrl` will be shown to your users. `callbackUrl` must match the callback URL provided in the OAuth request.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/NAFbFsTpQXOQmuRQqEYV_Screenshot%202015-07-27%2012.02.07.png\",\n        \"Screenshot 2015-07-27 12.02.07.png\",\n        \"2422\",\n        \"2182\",\n        \"#1f5c8a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nYou will need the UUID and Token for your application. Click `Generate Token` to get a new token.\n\nThe `UUID` will be your `Client ID` and `Token` is your `Client Secret`.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/K5bcJnG9TwWI8ZihYDGP_Screenshot%202015-07-27%2012.02.37.png\",\n        \"Screenshot 2015-07-27 12.02.37.png\",\n        \"2424\",\n        \"2180\",\n        \"#1e506f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nIn order for a user to OAuth with your application, you must allow it to be discoverable by Everything.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ohLDEkBnSW2UsOasAaZ8_Screenshot%202015-07-27%2012.02.20.png\",\n        \"Screenshot 2015-07-27 12.02.20.png\",\n        \"2428\",\n        \"2184\",\n        \"#1e5c8a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"OAuth Request\"\n}\n[/block]\nAll Octoblu OAuth requests are made using `https://oauth.octoblu.com/`.\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"/authorize\"\n}\n[/block]\nThis endpoint takes the user to app.octoblu.com to authorize your app and redirects back with either a 'code' or 'token'. \n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"client_id\",\n    \"0-1\": \"string\",\n    \"0-2\": \"The Client ID (`UUID`) you received when you created your application\",\n    \"1-0\": \"redirect_uri\",\n    \"1-1\": \"string\",\n    \"1-2\": \"The `callbackUrl` you entered when you created your application\",\n    \"2-0\": \"response_type\",\n    \"2-1\": \"string\",\n    \"2-2\": \"`code` or `token`\\n\\nNote:  Returns base64 'code' or 'access_token'\",\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"/access_token\"\n}\n[/block]\nOctoblu will redirect back to your application with a temporary `code`. Use this to exchange for a token.\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"client_id\",\n    \"0-1\": \"string\",\n    \"0-2\": \"Required. The Client ID (`UUID`) you received when you created your application.\",\n    \"1-0\": \"client_secret\",\n    \"1-1\": \"string\",\n    \"1-2\": \"Required. The Client Secret (`Token`) you received when you created your application.\",\n    \"2-0\": \"code\",\n    \"2-1\": \"string\",\n    \"2-2\": \"The `code` you received from Octoblu\",\n    \"3-0\": \"redirect_uri\",\n    \"3-1\": \"string\",\n    \"3-2\": \"The `callbackUrl` you entered when you created your application\",\n    \"4-0\": \"grant_type\",\n    \"4-1\": \"string\",\n    \"4-2\": \"Required. Supports `authorization_code`, `client_credentials`, or `refresh_token`\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n### Response\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"access_token=e72e16c7e42f292c6912e7710c838347ae17=\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the token\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: bearer e72e16c7e42f292c6912e7710c838347ae17=\\\" -H \\\"Content-Type: application/json\\\" https://meshblu.octoblu.com/v2/whoami\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Redirect URIs\"\n}\n[/block]\nThe redirect_uri parameter is required. The redirect URL’s host and port must exactly match the callback URL. The redirect URL’s path must reference a subdirectory of the callback URL.\n\n```\ncallbackUri: http://example.com/some/path\n\nGOOD: http://example.com/some/path\nGOOD: http://example.com/some/path/subdir/other\nBAD:  http://example.com/path\nBAD:  http://example.com/some\nBAD:  http://example.com/\nBAD:  http://example.com:8080/some/path\nBAD:  http://oauth.example.com:8080/some/path\nBAD:  http://example.org\n```","excerpt":"Octoblu / Meshblu OAuth","slug":"oauth","type":"basic","title":"OAuth"}

OAuth

Octoblu / Meshblu OAuth

[block:api-header] { "type": "basic", "title": "Getting Started" } [/block] OAuth allows your application to make authenticated requests on behalf of a user. You will need to register your application with Octoblu to get started. [block:api-header] { "type": "basic", "title": "Example Server" } [/block] Checkout [octoblu/octoblu-oauth-server-example](https://github.com/octoblu/octoblu-oauth-server-example) for a working example using Octoblu OAuth. [block:api-header] { "type": "basic", "title": "Register an Application" } [/block] To register a new OAuth application with Octoblu, first you will create an OAuth device. Visit the [Things](https://app.octoblu.com/node-wizard) page to add a new Thing. Select `OAuth Application`. [block:image] { "images": [ { "image": [ "https://files.readme.io/qzMOjpjPT22RuhgkG3Ie_Screenshot%202015-07-27%2011.59.32.png", "Screenshot 2015-07-27 11.59.32.png", "2432", "2182", "#14538b", "" ] } ] } [/block] Give your OAuth Application a name, this is for your reference and will not be shown to your users. [block:image] { "images": [ { "image": [ "https://files.readme.io/hTCefcv7QPGR2MwnPVcP_Screenshot%202015-07-27%2012.00.42.png", "Screenshot 2015-07-27 12.00.42.png", "2426", "2186", "#14548b", "" ] } ] } [/block] Fill in the properties. `name` and `imageUrl` will be shown to your users. `callbackUrl` must match the callback URL provided in the OAuth request. [block:image] { "images": [ { "image": [ "https://files.readme.io/NAFbFsTpQXOQmuRQqEYV_Screenshot%202015-07-27%2012.02.07.png", "Screenshot 2015-07-27 12.02.07.png", "2422", "2182", "#1f5c8a", "" ] } ] } [/block] You will need the UUID and Token for your application. Click `Generate Token` to get a new token. The `UUID` will be your `Client ID` and `Token` is your `Client Secret`. [block:image] { "images": [ { "image": [ "https://files.readme.io/K5bcJnG9TwWI8ZihYDGP_Screenshot%202015-07-27%2012.02.37.png", "Screenshot 2015-07-27 12.02.37.png", "2424", "2180", "#1e506f", "" ] } ] } [/block] In order for a user to OAuth with your application, you must allow it to be discoverable by Everything. [block:image] { "images": [ { "image": [ "https://files.readme.io/ohLDEkBnSW2UsOasAaZ8_Screenshot%202015-07-27%2012.02.20.png", "Screenshot 2015-07-27 12.02.20.png", "2428", "2184", "#1e5c8a", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "OAuth Request" } [/block] All Octoblu OAuth requests are made using `https://oauth.octoblu.com/`. [block:api-header] { "type": "get", "title": "/authorize" } [/block] This endpoint takes the user to app.octoblu.com to authorize your app and redirects back with either a 'code' or 'token'. [block:parameters] { "data": { "0-0": "client_id", "0-1": "string", "0-2": "The Client ID (`UUID`) you received when you created your application", "1-0": "redirect_uri", "1-1": "string", "1-2": "The `callbackUrl` you entered when you created your application", "2-0": "response_type", "2-1": "string", "2-2": "`code` or `token`\n\nNote: Returns base64 'code' or 'access_token'", "h-0": "Name", "h-1": "Type", "h-2": "Description" }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "type": "post", "title": "/access_token" } [/block] Octoblu will redirect back to your application with a temporary `code`. Use this to exchange for a token. [block:parameters] { "data": { "h-0": "Name", "h-1": "Type", "h-2": "Description", "0-0": "client_id", "0-1": "string", "0-2": "Required. The Client ID (`UUID`) you received when you created your application.", "1-0": "client_secret", "1-1": "string", "1-2": "Required. The Client Secret (`Token`) you received when you created your application.", "2-0": "code", "2-1": "string", "2-2": "The `code` you received from Octoblu", "3-0": "redirect_uri", "3-1": "string", "3-2": "The `callbackUrl` you entered when you created your application", "4-0": "grant_type", "4-1": "string", "4-2": "Required. Supports `authorization_code`, `client_credentials`, or `refresh_token`" }, "cols": 3, "rows": 5 } [/block] ### Response [block:code] { "codes": [ { "code": "access_token=e72e16c7e42f292c6912e7710c838347ae17=", "language": "http" } ] } [/block] [block:api-header] { "type": "basic", "title": "Using the token" } [/block] [block:code] { "codes": [ { "code": "curl -H \"Authorization: bearer e72e16c7e42f292c6912e7710c838347ae17=\" -H \"Content-Type: application/json\" https://meshblu.octoblu.com/v2/whoami", "language": "shell" } ] } [/block] [block:api-header] { "type": "basic", "title": "Redirect URIs" } [/block] The redirect_uri parameter is required. The redirect URL’s host and port must exactly match the callback URL. The redirect URL’s path must reference a subdirectory of the callback URL. ``` callbackUri: http://example.com/some/path GOOD: http://example.com/some/path GOOD: http://example.com/some/path/subdir/other BAD: http://example.com/path BAD: http://example.com/some BAD: http://example.com/ BAD: http://example.com:8080/some/path BAD: http://oauth.example.com:8080/some/path BAD: http://example.org ```