Access Token Handling

---

At a Glance

• Access token authenticates user sessions.
• Two login options: direct login API or embedded login screen.
• Token appears in a JSON field, cookie, or response header.
• Token appears in each request.
• Each valid request resets the token TTL.
• Token duration depends on the X-Platform value.
• Partners that use a master token issue only user tokens to clients.

---

Token Flow Overview

Flow Diagram

+------+        +--------------------+        +-----------------------+
|User  |        | Client Application |        | Air Doctor Login API  |
+--+---+        +---------+----------+        +-----------+-----------+
|                       |                               |
| Credentials           |                               |
+---------------------->| Login request                 |
|                       +----------------------------->|
|                       |                               |
|                       | Access token                  |
|                       |<-----------------------------+
|                       |                               |
|                       | Extract token                 |
|                       | Store token (secure store)    |
|                       |                               |
|                       | Request with token            |
|                       +----------------------------->|
|                       |                               |
|                       | Token validation, TTL reset   |
|                       |<-----------------------------+

---

Obtaining a Token

Air Doctor exposes a login API that issues an opaque access token for authenticated users. Partners use one of the following options:

• Direct login API call – Your backend server calls the Air Doctor login endpoint with user credentials and receives an access token in the response. This option is preferred when you manage your own users and issue tokens on their behalf.
• Embedded login screen – If you rely on Air Doctor for user management, you present the Air Doctor login screen to the user. The same login API runs behind the scenes and the resulting token appears as a cookie or in the response headers.

important

For either option, the token must be extracted from the response and stored securely.

Using the Token

The access token authenticates the user and authorizes user actions.

Token Essentials

Include the token with every request to Air Doctor servers, even for endpoints that allow anonymous access.

When a token exists,, include the token to enable consistent auditing and personalized responses. You can supply the token through the following:

Token Delivery Options

Token Delivery Method	When to Use
HTTP cookie	Set a session-token cookie when requests originate from a browser environment.
HTTP Authorization header	Use Authorization: Bearer <token> for OAuth-style authentication.
Custom header	Send X-Token: <token> when a bespoke header is preferred.
Query or form parameter	Include an x-token field in the query string or form data when other options are not convenient.

Token Lifetime and Renewal

Tokens have a time-limited nature and a time-to-live (TTL) value that starts with the last successful use of the token. Each valid API call resets the expiry clock. When the token remains unused beyond its TTL, the token expires and the user must log in again. The TTL depends on the X-Platform value that you specify when the token is created.

Lifecycle Summary

The lifecycle of an access token follows a fixed sequence.

[Login] -> [Token active] -> [Requests with token] -> [TTL reset] -> [Inactivity] -> [Expiry] -> [New login]

• Login creates the token.
• Valid requests keep the token active.
• Inactivity causes expiry.
• Expired token requires new login.

TTL Summary

API tokens do not expire. Native app tokens expire after 1 year. WebView tokens expire after 3 hours.

Token Duration by Platform

The table defines token duration for each supported platform.

X-Platform	Typical Client Scenario	Token Duration
API	Server-to-server integrations	Does not expire
iOS or Android	Native application	1 year
Mobile	Web application on a mobile device	3 months
Web	Desktop web application	1 month
Embedded	Embedded WebView with managed users	3 hours
Authorization-code	Internal use: temporary OAuth token	10 minutes

Third-party Considerations

For Partners That Use a Master Token

Apply strict controls to protect the master token and user tokens.

Minimum Required Controls

• Call login from your back-end – Use your master token only on the server.
• Send only user tokens to clients – Restrict client access to user tokens only.
• Rotate tokens as needed – Replace expired user tokens through the back end.
• Protect the master token – Maintain strict separation between client code and the master token.
• Avoid client-side refresh logic – Prevent any attempt to refresh or renew the master token on the client.

Common Mistakes

caution

• Embedding the master token in client code.
• Sending the master token to any user device.
• Relying on token refresh logic in the client.

Token Control Flow

[Master Token] -> [Backend Login Call] -> [User Token] -> [Client App] -> [API Requests]

These controls secure authentication flows and ensure correct token usage across partner implementations.