{"_id":"55f28173f9f3991900f38a17","user":"557e2561eb75d80d00af3dab","version":{"_id":"55f28172f9f3991900f38a13","project":"54ebb40d6423300d003672c0","__v":2,"createdAt":"2015-09-11T07:23:30.065Z","releaseDate":"2015-09-11T07:23:30.065Z","categories":["55f28172f9f3991900f38a14","55f28172f9f3991900f38a15","55f28172f9f3991900f38a16","55f66acb297b37170058accb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"__v":4,"category":{"_id":"55f28172f9f3991900f38a15","version":"55f28172f9f3991900f38a13","__v":1,"pages":["55f28173f9f3991900f38a17","55f28173f9f3991900f38a18","55f28173f9f3991900f38a19","55f28173f9f3991900f38a1a","55f28173f9f3991900f38a1b","55f28173f9f3991900f38a1c"],"project":"54ebb40d6423300d003672c0","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-06-17T04:27:26.544Z","from_sync":false,"order":1,"slug":"overview","title":"Overview"},"project":"54ebb40d6423300d003672c0","parentDoc":null,"updates":["5620f09ab244890d001868dc"],"next":{"pages":[],"description":""},"createdAt":"2015-06-17T04:27:46.162Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"All requests require an OAuth 2 access token. You can generate an access token in your [account settings](https://cloud.lifx.com/settings). Take care to keep access tokens private as they grant remote access to your lights.\n\nAuthenticate with HTTP Basic Authentication or the HTTP Authorization header. When using HTTP Basic Authentication the access token is the username and the password may be left blank. Bad access tokens will be rejected by responding with a `401 Forbidden` status code.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"All requests must be made over HTTPS. Requests made to the HTTP endpoint will be rejected with a `426 Upgrade Required` status code indicating that the connection must be remade using HTTPS to continue.\",\n  \"title\": \"HTTPS Requests Only\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP Authorization Header\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer [[app:Token]]\\\" \\\"https://api.lifx.com/v1/lights/all\\\"\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"<?php\\n\\n$link = \\\"https://api.lifx.com/v1/lights/all\\\";\\n$authToken = \\\"[[app:Token]]\\\";\\n$ch = curl_init($link);\\n$headers = array('Authorization: Bearer ' . $authToken);\\ncurl_setopt($ch, CURLOPT_HTTPHEADER, $headers);\\n$response = curl_exec($ch);\\n\\n?>\\n\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"import requests\\n\\ntoken = \\\"[[app:Token]]\\\"\\n\\nheaders = {\\n    \\\"Authorization\\\": \\\"Bearer %s\\\" % token,\\n}\\n\\nresponse = requests.get('https://api.lifx.com/v1/lights/all', headers=headers)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP Basic Authentication\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -u \\\"[[app:Token]]:\\\" \\\"https://api.lifx.com/v1/lights/all\\\"\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"<?php\\n\\n$link = \\\"https://api.lifx.com/v1/lights/all\\\";\\n$authToken = \\\"[[app:Token]]\\\";\\n$ch = curl_init($link);\\ncurl_setopt($ch, CURLOPT_USERPWD, $authToken . \\\":\\\");\\n$response = curl_exec($ch);\\n\\n?>\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"import requests\\n\\ntoken = \\\"[[app:Token]]\\\"\\n\\nresponse = requests.get('https://api.lifx.com/v1/lights/all', auth=(token, ''))\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n# OAuth Access\n\n## Obtaining tokens for your application \n\nLIFX is currently providing OAuth application access to select third parties. This enables your application to get an access token for your users in an automated manner. If you would like to participate in this program please email us at developer:::at:::lifx.com for consideration. Please include the following information:\n\n* Your application name, and the name of the company that owns it. If you are building it as a personal project we can use your legal name here instead.\n* Your logo. We prefer SVG or EPS format, but otherwise we will need a 425x425 PNG file.\n* A Redirect URL. The URL we should redirect to once the OAuth flow is complete.\n* Your Homepage URL. The URL of your homepage,\n* Description. Describe what your application does, and why it needs access to a users LIFX account.\n\nWe will send you this information for use as part of your oauth flow.\n\n* The `client_id` and `client_secret` for your app\n* The authorization URL\n* The token URL\n* The scope to request\n\n## Obtaining Credentials for a User\n\n### 1. Open the Authorization page\nThe Authorization URL is:\n\n    https://cloud.lifx.com/oauth/authorize\n\nYou should make a GET request to this URL with the following information in the request parameters:\n\n\n| Name          | Type   | Description                                                     |\n|---------------|--------|-----------------------------------------------------------------|\n| client_id     | string | The Token you were provided for your application.               |\n| scope         | string | The scope you were told to use. Eg. `remote_control:all`.       |\n| state         | string | A random unguessable string to prevent CSS attacks.             |\n| response_type | string | Must be set to `code`, per the [OAuth2 specification](http://tools.ietf.org/html/rfc6749#section-4.1.1). |\n\n\nAt this page the user will be asked to login if they haven't yet, and then they will be asked to give permissions to your application.\n\n### 2. LIFX redirects to your redirect URL\n\nOnce the user makes the decision they will be redirected to the `redirect_uri` that you provided us, with the results of the decision. The following will be provided as URL parameters:\n\n| Name         | Type   | Description                                                                        |\n|--------------|--------|------------------------------------------------------------------------------------|\n| code         | string | A code that can be exchanged for a users access token.                             |\n| state        | string | Should be the same as the provided `state` parameter, otherwise reject the request. |\n\n### 3. Exchange the code for the users Access Token.\n\nThe token URL is:\n\n    https://cloud.lifx.com/oauth/token\n\nTo exchange the code for a users access token a POST should be made to this URL with the following parameters:\n\n| Name          | Type   | Description                                                                        |\n|---------------|--------|------------------------------------------------------------------------------------|\n| client_id     | string | The Token you were provided for your application.                                  |\n| client_secret | string | The Secret Token you were provided for your application.                           |\n| code          | string | The `code` you received in the previous step (Step 2).                             |\n| grant_type    | string | Must be set to `authorization_code`.                                               |\n\nThe response from this request will be a JSON object containing the access token. An example response may look like this:\n\n    {\n        \"access_token\": \"c52826c87adfa1aa5cc85c87df245e2afdd4bb6c361687bd29869432470cc68d\",\n        \"refresh_token\": \"c523f5f66b6b25e050a8fbe26c2eff784e4ecb803e527e5859d3ed009c4db6bc\",\n        \"token_type\": \"Bearer\"\n    }\n\nYou can now use the `access_token` as described in the [HTTP API Authentication](https://api.developer.lifx.com/docs/authentication) Documentation.","excerpt":"Proving that you have access to the right account","slug":"authentication","type":"basic","title":"Authentication"}

Authentication

Proving that you have access to the right account

All requests require an OAuth 2 access token. You can generate an access token in your [account settings](https://cloud.lifx.com/settings). Take care to keep access tokens private as they grant remote access to your lights. Authenticate with HTTP Basic Authentication or the HTTP Authorization header. When using HTTP Basic Authentication the access token is the username and the password may be left blank. Bad access tokens will be rejected by responding with a `401 Forbidden` status code. [block:callout] { "type": "danger", "body": "All requests must be made over HTTPS. Requests made to the HTTP endpoint will be rejected with a `426 Upgrade Required` status code indicating that the connection must be remade using HTTPS to continue.", "title": "HTTPS Requests Only" } [/block] [block:api-header] { "type": "basic", "title": "HTTP Authorization Header" } [/block] [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer [[app:Token]]\" \"https://api.lifx.com/v1/lights/all\"", "language": "curl" }, { "code": "<?php\n\n$link = \"https://api.lifx.com/v1/lights/all\";\n$authToken = \"[[app:Token]]\";\n$ch = curl_init($link);\n$headers = array('Authorization: Bearer ' . $authToken);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, $headers);\n$response = curl_exec($ch);\n\n?>\n", "language": "php" }, { "code": "import requests\n\ntoken = \"[[app:Token]]\"\n\nheaders = {\n \"Authorization\": \"Bearer %s\" % token,\n}\n\nresponse = requests.get('https://api.lifx.com/v1/lights/all', headers=headers)", "language": "python" } ] } [/block] [block:api-header] { "type": "basic", "title": "HTTP Basic Authentication" } [/block] [block:code] { "codes": [ { "code": "curl -u \"[[app:Token]]:\" \"https://api.lifx.com/v1/lights/all\"", "language": "curl" }, { "code": "<?php\n\n$link = \"https://api.lifx.com/v1/lights/all\";\n$authToken = \"[[app:Token]]\";\n$ch = curl_init($link);\ncurl_setopt($ch, CURLOPT_USERPWD, $authToken . \":\");\n$response = curl_exec($ch);\n\n?>", "language": "php" }, { "code": "import requests\n\ntoken = \"[[app:Token]]\"\n\nresponse = requests.get('https://api.lifx.com/v1/lights/all', auth=(token, ''))\n", "language": "python" } ] } [/block] # OAuth Access ## Obtaining tokens for your application LIFX is currently providing OAuth application access to select third parties. This enables your application to get an access token for your users in an automated manner. If you would like to participate in this program please email us at developer@lifx.com for consideration. Please include the following information: * Your application name, and the name of the company that owns it. If you are building it as a personal project we can use your legal name here instead. * Your logo. We prefer SVG or EPS format, but otherwise we will need a 425x425 PNG file. * A Redirect URL. The URL we should redirect to once the OAuth flow is complete. * Your Homepage URL. The URL of your homepage, * Description. Describe what your application does, and why it needs access to a users LIFX account. We will send you this information for use as part of your oauth flow. * The `client_id` and `client_secret` for your app * The authorization URL * The token URL * The scope to request ## Obtaining Credentials for a User ### 1. Open the Authorization page The Authorization URL is: https://cloud.lifx.com/oauth/authorize You should make a GET request to this URL with the following information in the request parameters: | Name | Type | Description | |---------------|--------|-----------------------------------------------------------------| | client_id | string | The Token you were provided for your application. | | scope | string | The scope you were told to use. Eg. `remote_control:all`. | | state | string | A random unguessable string to prevent CSS attacks. | | response_type | string | Must be set to `code`, per the [OAuth2 specification](http://tools.ietf.org/html/rfc6749#section-4.1.1). | At this page the user will be asked to login if they haven't yet, and then they will be asked to give permissions to your application. ### 2. LIFX redirects to your redirect URL Once the user makes the decision they will be redirected to the `redirect_uri` that you provided us, with the results of the decision. The following will be provided as URL parameters: | Name | Type | Description | |--------------|--------|------------------------------------------------------------------------------------| | code | string | A code that can be exchanged for a users access token. | | state | string | Should be the same as the provided `state` parameter, otherwise reject the request. | ### 3. Exchange the code for the users Access Token. The token URL is: https://cloud.lifx.com/oauth/token To exchange the code for a users access token a POST should be made to this URL with the following parameters: | Name | Type | Description | |---------------|--------|------------------------------------------------------------------------------------| | client_id | string | The Token you were provided for your application. | | client_secret | string | The Secret Token you were provided for your application. | | code | string | The `code` you received in the previous step (Step 2). | | grant_type | string | Must be set to `authorization_code`. | The response from this request will be a JSON object containing the access token. An example response may look like this: { "access_token": "c52826c87adfa1aa5cc85c87df245e2afdd4bb6c361687bd29869432470cc68d", "refresh_token": "c523f5f66b6b25e050a8fbe26c2eff784e4ecb803e527e5859d3ed009c4db6bc", "token_type": "Bearer" } You can now use the `access_token` as described in the [HTTP API Authentication](https://api.developer.lifx.com/docs/authentication) Documentation.