Web API and OAuth

Aidlab Web API access is based on OAuth clients created in Aidlab Cloud. Use this flow when an approved partner application needs access to supported data from an individual Aidlab user.

Create an OAuth client

1. Open Aidlab Cloud with an account that has developer access enabled.
2. Go to Shortcuts → Developers.
3. Click Create API key.
4. Enter an application name and redirect URI.
5. Select one or more available scopes for your integration.
6. Copy the client secret when it is shown.

The client secret is displayed only once. Store it in your backend secret manager and never place it in mobile apps, browser code, GitHub, or public logs.

Scopes

Aidlab currently exposes these OAuth scopes:

Scope	Description
data:read	Read supported health data and user events.
data:write	Create or import supported health data.
profile:read	Read the authorized user profile.

Current OAuth access does not include sessions or locations. OAuth tokens are accepted only on endpoints explicitly mapped to OAuth scopes.

You can also discover the current list programmatically:

curl https://my.aidlab.com/api/oauth/scopes

Authorization code flow

Send the user to Aidlab to approve your application. The user must be logged in to Aidlab Cloud.

https://my.aidlab.com/oauth/authorize
  ?response_type=code
  &client_id=aid_live_...
  &redirect_uri=https%3A%2F%2Fpartner.example%2Foauth%2Fcallback
  &scope=data%3Aread%20profile%3Aread
  &state=opaque-state

Parameters:

Parameter	Required	Description
response_type	Yes	Must be code.
client_id	Yes	Public client ID from the Developers page.
redirect_uri	Yes	Must match one of the redirect URIs registered for the client.
scope	No	Space-delimited scopes. If omitted, Aidlab uses the scopes configured on the client.
state	No	Opaque value returned to your redirect URI. Use it to protect against CSRF.

After the user approves access, Aidlab redirects to your callback:

https://partner.example/oauth/callback?code=returned_code&state=opaque-state

If the user denies access, Aidlab redirects with:

https://partner.example/oauth/callback?error=access_denied&state=opaque-state

Exchange the code for a token

Exchange the authorization code from your backend. Authorization codes are one-time use.

curl https://my.aidlab.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "aid_live_...",
    "client_secret": "secret_...",
    "grant_type": "authorization_code",
    "code": "returned_code",
    "redirect_uri": "https://partner.example/oauth/callback"
  }'

Response:

{
  "token": "bearer_token",
  "value": "bearer_token",
  "refreshToken": "refresh_token",
  "refresh_token": "refresh_token",
  "expiresIn": 86400,
  "expires_in": 86400,
  "token_type": "Bearer",
  "scope": ["data:read", "profile:read"]
}

Access tokens are short-lived. Store the refresh token on your backend and use it to obtain a new access token without asking the user to approve the app again.

Refresh an access token

Refresh tokens are rotated. When you refresh an access token, store the new refresh token from the response and discard the old one.

curl https://my.aidlab.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "aid_live_...",
    "client_secret": "secret_...",
    "grant_type": "refresh_token",
    "refresh_token": "refresh_token"
  }'

Response:

{
  "token": "new_bearer_token",
  "value": "new_bearer_token",
  "refreshToken": "new_refresh_token",
  "refresh_token": "new_refresh_token",
  "expiresIn": 86400,
  "expires_in": 86400,
  "token_type": "Bearer",
  "scope": ["data:read", "profile:read"]
}

Use the token in API requests:

curl https://my.aidlab.com/api/users/me \
  -H "Authorization: Bearer bearer_token"

Server-to-server tokens

For owner-controlled backend jobs, you can use client credentials instead of user consent:

curl https://my.aidlab.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "aid_live_...",
    "client_secret": "secret_...",
    "grant_type": "client_credentials",
    "scope": ["data:read"]
  }'

Use authorization code flow for third-party apps that access a user’s data. Use client credentials only for server-to-server work owned by the Aidlab account that created the client.

Security behavior

OAuth client tokens can access only endpoints that Aidlab maps to OAuth scopes. Unknown endpoints are rejected with 403.

OAuth client tokens cannot use Aidlab’s internal scoped-user header. Third-party integrations must obtain user access through the authorization code flow.

Users can revoke connected apps in Aidlab Cloud. After revocation, refresh-token requests fail and active access tokens stop working.