The Airthings API supports two OAuth2 methods of authorizing access to data through the API.

• Code Flow Grant
• Client Credentials Grant

Both are based on the Airthings Accounts Authentication service.

Authorizing through Code Flow

To authorize an app to read the device data of an account, OAuth2 Code Flow can be used.

The user of the app should be redirected to accounts.airthings.com/authorize?client_id={appClientId}&redirect_uri={appRedirectUri} for authorization:

• Sign in with their Airthings credentials
• Authorize the app to read data on their behalf

Once this is complete, the user is redirected from the accounts app back to the app located at the url from redirect_uri with an authorization code. The authorization code in turn can be exchanged for an access_token on the /token endpoint.

• Authorization URL: https://accounts.airthings.com/authorize
• Token URL: https://accounts-api.airthings.com/v1/token

After authorize the token endpoint is to be called with a payload similar to:

{
	"grant_type": "authorization_code",
	"client_id": "b8a19a7d-64cd-4281-xxxx-3ffacc726fe3",
	"client_secret": "82bfed8b-793a-4423-xxxx-7491303354a0",
	"code": "auth-code-from-authorize",
	"redirect_uri": "https://redirect.configured.for.client"
}

Refreshing the access_token

The access-token has a short life-time (seconds can be seen in the token response expires_in). Using an expired access-token towards the API will result in an error response with status code 401, signalling a refresh is needed.
When using the code flow the access-token can be refreshed by using a refresh-token. Upon refresh (and code_grant) a new refresh-token is provided. It is important to store the new refresh-token upon refresh, since this token also has a fixed life-time.

To refresh the access-token, the token endpoint: https://accounts-api.airthings.com/v1/token is called with a refresh-grant payload:

{
	"grant_type": "refresh_token",
	"client_id": "b8a19a7d-64cd-4281-xxxx-3ffacc726fe3",
	"client_secret": "82bfed8b-793a-4423-xxxx-7491303354a0",
	"refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJ....."
}

Using an expired refresh-token yields an error response with a status code 4xx.

Note: in Client Credentials Grant (below) no refresh_token is provided. Hence, there no refreshing is possible.

Authorizing a Client Credentials Grant

Especially for machine-to-machine (M2M) authentication we have implemented Client Credentials from the OAuth2 spec.

NOTE: Using this flow for frontend authentication to the API is not recommended, since only a backend can maintain the integrity of a client secret.

To setup a client for M2M, create a client for your app, as described above (configured for Client Credentials as Flow type). Next use the client id and client secret to request a token from the accounts-api. The scope specifies what type of operation you want to use. For the date fetching endpoints, the correct scope would be the read:device scope. For writing/posting, use the write:device scope.

Token URL: https://accounts-api.airthings.com/v1/token

{
    "grant_type":"client_credentials",
    "client_id":"b8a19a7d-64cd-4281-xxxx-3ffacc726fe3",
    "client_secret":"82bfed8b-793a-4423-xxxx-7491303354a0",
    "scope": ["read:device"]
}

The token from the response can be used to access the endpoints in the API until it expires. After the token is expired (time for expires_in is provided in seconds in the response) the token endpoint has to be called again. Using an expired access-token will result in an error response with status code 401.