{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c9a99c37-d1a1-4d7e-83f4-f11928710a05","name":"Awair Home & OAuth Developer APIs","description":"- [Disclaimer](#disclaimer)\n    \n- [Getting Started](#getting-started)\n    \n    - [The Hobbyist Developer Console](#the-hobbyist-developer-console)\n        \n- [First Steps](#first-steps)\n    \n    - [Bearer Token](#bearer-token)\n        \n- [Organizations](#organizations)\n    \n- [OAuth 2 Clients](#oauth-2-clients)\n    \n    - [Access Request and Token Exchange](#access-request-and-token-exchange)\n        \n        - [Access Request Parameters](#access-request-parameters)\n            \n        - [Token Exchange Request Parameters](#token-exchange-request-parameters)\n            \n        - [Token Exchange Response](#token-exchange-response)\n            \n- [Tiers and Quotas](#tiers-and-quotas)\n    \n    - [Tier Quotas](#tier-quotas)\n        \n- [Data Guide](#data-guide)\n    \n    - [Units of Measure](#units-of-measure)\n        \n    - [Awair Score and Index](#awair-score-and-index)\n        \n- [Test Requests](#test-requests)\n    \n    - [Hobbyist](#hobbyist)\n        \n- [What's Next?](#whats-next)\n    \n    - [Local API](#local-api)\n        \n\n# Disclaimer\n\nPlease be careful when sharing any API key with any 3rd parties! By sharing your API key with 3rd parties, you agree to Awair’s Terms of Service.\n\n“Awair’s Terms of Service” should be underlined and linked to [https://www.getawair.com/legal/terms](https://www.getawair.com/legal/terms)\n\n# Getting Started\n\nWelcome to the Awair Hobbyist Developer APIs! This page aims to get you started quickly and explain some basic concepts. If you are looking for the Dashboard Developer APIs, you can find them here: [https://docs.dashboard.getawair.com](https://docs.dashboard.getawair.com)\n\n## The Awair Home Developer Console\n\nThe [Awair Home Developer Console](https://developer.getawair.com) is your gateway to the Developer APIs. From here you can manage your account, get your account API token, and register OAuth 2.0 clients.\n\nThe Dashboard Developer Console is accessible in the left side menu of your [Dashboard Organization](https://dashboard.getawair.com) as long as your account has the Organization Manager role permissions.\n\n# First Steps\n\nAll of our endpoints use a [Bearer Token](https://developer.getawair.com/console/access-token) for authorization. It should be included in the Authorization Header (as a `Bearer` token) for any request. For example:\n\n``` shell\ncurl -X GET https://developer-apis.awair.is/ -H 'authorization: Bearer {{yourBearerToken}}'\n\n ```\n\nThe Bearer Token can be copied straight from the [Bearer Token](https://developer.getawair.com/console/access-token) section if you want to use your personal token (to access your devices), or generated through the OAuth 2 flow (to access data on behalf of your users).\n\nAll the endpoints are documented in our [API documentation](https://docs.developer.getawair.com/).\n\n## Bearer Token\n\nYour [Bearer Token](https://developer.getawair.com/console/access-token) is an API token that is automatically generated for your account. This token is all you need to start using our APIs, but note which endpoints you are authorized to use as it depends on the permissions your account (or in the case of an OAuth App your client's account) has been granted.\n\n# Organizations\n\nPlease use the new API Key available in the Dashboard or [contact sales](https://mailto:business@getawair.com) in order to purchase an Enterprise API subscription.\n\nIf you are looking for the Dashboard Developer APIs, you can find them here: [https://docs.dashboard.getawair.com](https://docs.dashboard.getawair.com)\n\n# OAuth 2 Clients\n\nOAuth 2.0 is an authentication system that allows 3rd-party apps to access Awair data on behalf of Awair users. A user with an Awair account can send an Authorization Grant to the third-party app by logging in through the Awair page. This Authorization Grant can be exchanged for an API token. When used in a call to the Awair Developer API, this token allows the app to make requests as if it were the user and is governed separately by our [OAuth Client API Terms &amp; Conditions](https://www.getawair.com/legal/terms?tab=api).\n\n```\nOAuth 2 apps can only retrieve Awair Home app \"USER\" account devices.\nHowever, it cannot be used to access Awair Business app \"ORG\" devices.\n\n ```\n\n<img src=\"https://links.awair.is/images/assets/awair-oauth-2-flow.jpg\">\n\n## Access Request and Token Exchange\n\n1. Apps request access from users by directing the user to the Awair login page by calling:\n    \n    GET [https://oauth-login.awair.is](https://oauth-login.awair.is)  \n    The list of query parameters is detailed in the API list at the bottom of this section, but note that **response_type** must always be set to `\"code\"`.\n    \n2. The user will see a login page, where they input their Awair credentials. If the user inputs the wrong credentials, they will remain on the login page.\n    \n3. Upon entry of recognized credentials, the browser environment is redirected to the specified **redirect_uri**, with the following query parameters:  \n    GET {{redirect_uri}}?code={{code}}&state={{state}}  \n    **Note:** The `code` parameter is the Authorization Grant from the user, while `state` is application-specific.\n    \n4. Token exchange is done in 2 parts. The first call should exchange the _Authorization Grant_ from step 3 to a _Refresh Token_ and a short-lived _API Token_, while all subsequent calls should use the _Refresh Token_ to renew the _API Token_.  \n    In either case, the same endpoint is called:  \n    POST [https://oauth2.awair.is/v2/token](https://oauth2.awair.is/v2/token) {\"message\": \"jwt expired\"}  \n    Note: The request must include the `client_id` and `client_secret` of the same Client that were submitted as query parameters in step 1.  \n    **Authorization Grant**  \n    To exchange an \"Authorization Grant\", the endpoint should be called with `grant_type` set to `authorization_code`, and `code` set to the value returned from step 3.  \n    The response body will include the `access_token` field, which is a short-lived \"API Token\". It also includes the field `refresh_token`, which should be permanently stored by your application for future use.  \n    **Refresh Token**  \n    Once an \"API Token\" expires, any calls to the Awair Developer API will have a response with status code `422` with the body containing JSON:  \n    When this occurs, a new token exchange must be performed. In this case, the `grant_type` parameter should be set to `refresh_token` and the `refresh_token` parameter should be set to the \"Refresh Token\" that was obtained in the initial response from the \"Authorization Grant\" request.  \n    The response will be the same as in the \"Authorization Grant\" request, but without the `refresh_token` field.\n    \n5. The response will include the API token. This token can be used to make requests to the Awair Developer API in the name of the user.\n    \n\n### Access Request Parameters\n\nThe following parameters should be submitted as request parameters\n\n| Name | Type | Required Value | Required | Description |\n| --- | --- | --- | --- | --- |\n| `state` | string |  | yes | Can be used to hold application specific information, e.g. user ID. |\n| `scope` | string |  | yes |  |\n| `response_type` | string | `\"code\"` | yes |  |\n| `client_id` | string |  | yes | Taken from Create OAuth 2.0 Client page. |\n| `redirect_uri` | string |  | yes | The browser will be redirected to this page once login is complete. |\n\n### Token Exchange Request Parameters\n\nThe following parameters should be submitted as JSON in the request body.\n\n| Name | Type | Required Value | Required | Description |\n| --- | --- | --- | --- | --- |\n| `client_id` | string |  | yes | Taken from Create OAuth 2.0 Client page. |\n| `client_secret` | string |  | yes | Taken from Create OAuth 2.0 Client page. |\n| `grant_type` | string | `authorization_code` | yes |  |\n|  |  | OR `refresh_token` |  |  |\n| `code` | string |  | yes | The `code` returned as a query parameters (See step 3). |\n\n### Token Exchange Response\n\nThe following will be returned as JSON in the response body.\n\n| Name | Type | Required Value | Required | Description |\n| --- | --- | --- | --- | --- |\n| `token_type` | string | `Bearer` | yes | Marks `access_token` as a \"Bearer Token\" |\n| `access_token` | string |  | yes | API \"Access Token\" |\n\n# Tiers and Quotas\n\nYour account has a Tier, which determines which endpoints you have access to and how many requests you can make on each endpoint per day (resets at midnight 00:00:00 UTC).\n\nList of Tiers:\n\n- Hobbyist (default)\n    \n\nThe default Tier (Hobbyist) is assigned free of charge when you first get access to the Developer Console, but the number of requests per day (UTC) and list of available endpoints will be assigned a Quota based on your Tier (see below: [Tier Quotas](#tier-quotas)).\n\nEach endpoint requires permission to access it via your Tier. While our APIs are in `Beta`, Tiers are managed by the Awair Team, so for now you should [contact us](https://mailto:developer@getawair.com) if your account isn't automatically approved or you would like to request a higher Quota / Tier.\n\nTo lookup your current Tier and Quotas, you can make a request on the [<b>User Info</b> endpoint](#6cfeb8fe-4910-4d4e-b11d-e7a2b62220b6) (link to documentation section):\n\n``` shell\ncurl -X GET https://developer-apis.awair.is/v1/users/self -H 'authorization: Bearer {{yourBearerToken}}'\n\n ```\n\n## Tier Quotas\n\n**Note:** Quotas are per device per endpoint per day (resets at midnight 00:00:00 UTC).\n\nIf you are looking for the Dashboard Developer APIs, you can find them here: [https://docs.dashboard.getawair.com](https://docs.dashboard.getawair.com)\n\n| Endpoint | Hobbyist |\n| --- | --- |\n| **User Details** |  |\n| USER_INFO | ∞ |\n| USER_DEVICE_LIST | ∞ |\n| DEVICE_API_USAGE | ∞ |\n|  |  |\n| **AirData** |  |\n| LATEST | 300 |\n| RAW | 500 |\n| FIVE_MIN | 300 |\n| FIFTEEN_MIN | 100 |\n|  |  |\n| **Device Management** |  |\n| PUT_DEVICE_NAME | 300 |\n| GET_DISPLAY_MODE | 300 |\n| PUT_DISPLAY_MODE | 300 |\n| GET_KNOCKING_MODE | 300 |\n| PUT_KNOCKING_MODE | 300 |\n| GET_LED_MODE | 300 |\n| PUT_LED_MODE | 300 |\n| PUT_LOCATION | 300 |\n| GET_POWER_STATUS | 300 |\n| PUT_PREFERENCE | 300 |\n| PUT_ROOM_TYPE | 300 |\n| PUT_SPACE_TYPE | 300 |\n| GET_TIMEZONE | 300 |\n| PUT_TIMEZONE | 300 |\n\n# Data Guide\n\n## Units of Measure\n\n| Device Type | Sensor | Sensor Description | Units | Units Description | Range |\n| --- | --- | --- | --- | --- | --- |\n| awair-r2, awair-element | temp | Temperature | °C | degrees Celsius | \\-40 \\~ 185 |\n| awair-r2, awair-element | humid | Relative Humidity | % | relative humidity (RH%) | 0 \\~ 100 |\n| awair-r2, awair-element | co2 | Carbon Dioxide (CO₂) | ppm | parts per million | 0 \\~ 5,000 |\n| awair-r2, awair-element | voc | Total Volatile Organic Compounds (TVOCs) | ppb | parts per billion | 175 \\~ 3,500 |\n| awair-r2, awair-element | pm25 | Particulate Matter (PM2.5 - Fine Dust) | μg/m³ | micrograms per meter cubed | 0 \\~ 1,000 |\n\n## Awair Score and Index\n\n<img src=\"https://content.pstmn.io/63a29ed8-7754-4752-98dc-f00d03a529b4/U2NyZWVuc2hvdCAyMDIyLTExLTMwIGF0IDMuNDguMDUgUE0ucG5n\" width=\"711\" height=\"986\">\n\n# Test Requests\n\nFor easier testing, we've created a set of tokens that simulate fake accounts with a given Tier. Dummy data is returned if the request is authorized, HTTP 401 if not.\n\nThe examples in the documentation all use the Hobbyist Tier Bearer Token, but we have listed the other dummy tokens below as well as download links to [Postman Environment .json files with example variables](https://learning.getpostman.com/docs/postman/environments_and_globals/variables/) so that you can test in your own Environment.\n\n## Hobbyist\n\n```\neyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiRFVNTVktSE9CQllJU1QifQ.hzjhIpGljqCZ8vCrOr89POy_ENDPYQXsnzGslP01krI\n\n ```\n\n\\[Download Postman Environment Hobbyist Variables\\]([https://links.awair.is/download/postman/[TEST]](https://links.awair.is/download/postman/%5BTEST%5D) Hobbyist.postman_environment.json)\n\n# What's Next?\n\nBy using our [API documentation](https://docs.developer.getawair.com/) to craft requests you should be well-armed to create awesome projects with our APIs, but our documentation can always be improved so don't hesitate to reach out with feedback or suggestions!\n\n# Local API\n\nIf the Developer APIs do not provide what you want or if you would like to test a local implementation of the `/latest` data endpoint on your Awair device you can learn more about \"Local API\" feature here: [Local API Documentation](https://bit.ly/awair-local-api-feature)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"7741371","team":373874,"collectionId":"c9a99c37-d1a1-4d7e-83f4-f11928710a05","publishedId":"S1TYTauC","public":true,"publicUrl":"https://docs.developer.getawair.com","privateUrl":"https://go.postman.co/documentation/7741371-c9a99c37-d1a1-4d7e-83f4-f11928710a05","customColor":{"top-bar":"001529","right-sidebar":"212528","highlight":"119BFF"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2020-12-11T20:34:01.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"[TEST] Hobbyist Developer API Token","id":"05c3e26f-8480-41d6-aa8f-004ce8fea431","owner":"7741371","values":[{"key":"example-token","value":"example-token","enabled":true},{"key":"user_id","value":"user_id","enabled":true},{"key":"user_id2","value":"user_id2","enabled":true},{"key":"from","value":"from","enabled":true},{"key":"to","value":"to","enabled":true},{"key":"limit","value":"limit","enabled":true},{"key":"desc","value":"desc","enabled":true},{"key":"fahrenheit","value":"fahrenheit","enabled":true},{"key":"org_id","value":"org_id","enabled":true},{"key":"device_type","value":"device_type","enabled":true},{"key":"device_id","value":"device_id","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/869f9beb9abb942de9482462137b60ac3572886896ae34e590d0b38a308ab045","favicon":"https://res.cloudinary.com/postman/image/upload/v1586919245/team/dv8roz50r2lvq5r0daok.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"[TEST] Hobbyist Developer API Token","value":"7741371-05c3e26f-8480-41d6-aa8f-004ce8fea431"}],"canonicalUrl":"https://docs.developer.getawair.com/view/metadata/S1TYTauC"}