Authorization and Security

InsideTracker APIs use bearer tokens to authorize requests. Integrations use two token levels:

Service-level tokens for Partner-level operations.
Customer-level tokens for operations tied to one linked InsideTracker customer record.

Use this guide to choose the right token, refresh access safely, recover customer credentials when needed, and keep credentials secure.

Service-level tokens

Use service-level tokens when your backend acts as your organization.

Customer-level tokens

Use customer-level tokens when your backend acts for a specific linked customer record.

Token Levels

Use the least-privileged token that matches the operation.

Token level	Represents	Use it for
Service-level token	Your organization or backend service.	Creating linked customer records, recovering customer token pairs, and managing Partner-level resources.
Customer-level token	One linked InsideTracker customer record for your User.	Adding User data, connecting User data sources, retrieving User outputs, and other User-specific operations.

A service-level token should not be used for customer-level endpoints when a customer-level token is expected. A customer-level token should not be used for Partner-level endpoints.

Environments

Use the sandbox environment while building and testing:

https://api.sandbox.insidetracker.com

Keep sandbox and production credentials separate. Do not reuse sandbox tokens or test data in production workflows.

Authorization Header

For authenticated requests, send the access token as a bearer token:

Authorization: Bearer {access_token}

Common auth-related responses include:

Status	Meaning
`401`	The request is not authenticated. The token may be missing, invalid, expired, or from the wrong environment.
`403`	The request is authenticated, but the token does not provide access to that operation.

Request A Service-Level Token

Use a service-level token when your backend needs to act as your organization.

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "audience": "customer_api"
}

Request fields:

Field	Required?	Description
`grant_type`	Yes	OAuth grant type. Use `client_credentials` when requesting a service-level token.
`client_id`	Yes	Client identifier issued for your organization.
`client_secret`	Yes	Client secret issued for your organization. Store and send it only from a secure backend.
`audience`	Yes	API audience for the token request, such as `customer_api`.

The response includes an access token, refresh token, token type, granted scope, and expiration:

{
  "access_token": "{service_access_token}",
  "token_type": "Bearer",
  "refresh_token": "{service_refresh_token}",
  "scope": "{granted_scopes}",
  "expires_in": 86400
}

Response fields:

Field	Description
`access_token`	Bearer token used for authenticated service-level requests until it expires.
`token_type`	Token type returned by the OAuth endpoint.
`refresh_token`	Token used to request a new access token. Store it securely.
`scope`	Scopes granted to the returned token.
`expires_in`	Lifetime of the access token in seconds. Use this value to refresh before expiration.

Use the access token until it expires. Store the refresh token securely and use the returned expires_in value to refresh access before requests fail.

Refresh A Service-Level Token

Access tokens expire. Use the refresh token to continue making service-level API requests.

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "{client_id}",
  "refresh_token": "{service_refresh_token}",
  "audience": "customer_api"
}

Request fields:

Field	Required?	Description
`grant_type`	Yes	OAuth grant type. Use `refresh_token` when refreshing an existing token pair.
`client_id`	Yes	Client identifier issued for your organization.
`refresh_token`	Yes	Latest stored service refresh token.
`audience`	Yes	API audience for the token request, such as `customer_api`.

Successful response:

The endpoint returns the same token response fields described above. Replace the stored service access token and refresh token with the returned values.

Get Customer-Level Tokens

Customer-level tokens are returned when you create a linked InsideTracker customer record for your User.

POST /enterprise/customers/sa/v1/customers/register
Content-Type: application/json
Authorization: Bearer {service_access_token}

For each successful response item, store the returned extId and customer token pair:

{
  "credentials": {
    "accessToken": "{customer_access_token}",
    "refreshToken": "{customer_refresh_token}"
  },
  "email": "[email protected]",
  "extId": "b2d905cd-e5ff-4843-817e-cc27a916c90c",
  "succeed": true,
  "errors": []
}

Response fields:

Field	Description
`credentials.accessToken`	Customer-level access token for User-specific API requests.
`credentials.refreshToken`	Customer-level refresh token. Store it securely with the linked customer record.
`email`	Email address associated with the created or returned customer record.
`extId`	Durable mapping key between your User and the linked InsideTracker customer record.
`succeed`	Indicates whether that response item completed successfully.
`errors`	Validation or processing errors for that response item, when present.

The extId is the durable mapping between your User record and the linked InsideTracker customer record.

Refresh A Customer-Level Token

Use the customer OAuth token endpoint to refresh a customer token pair.

POST /customer/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "{client_id}",
  "refresh_token": "{customer_refresh_token}"
}

Request fields:

Field	Required?	Description
`grant_type`	Yes	OAuth grant type. Use `refresh_token` when refreshing an existing customer token pair.
`client_id`	Yes	Client identifier issued for your organization.
`refresh_token`	Yes	Latest stored customer refresh token for the linked customer record.

Successful response:

The response returns a new customer access token and refresh token. Update the stored token pair after a successful refresh.

Recover Lost Customer Tokens

If a customer token pair is lost or broken, recover it with a service-level token.

POST /enterprise/customers/sa/v1/customers/recreate-tokens
Content-Type: application/json
Authorization: Bearer {service_access_token}

[
  {
    "extId": "b2d905cd-e5ff-4843-817e-cc27a916c90c"
  }
]

Request fields:

Field	Required?	Description
`extId`	Yes	Durable mapping key for the linked customer record whose customer token pair needs to be recovered.

Successful response:

The endpoint returns recovery results for the requested linked customer records. Use token recovery only when the current customer token pair cannot be refreshed or used. Recreating customer tokens can invalidate the previous token pair, so replace stored credentials with the newly returned values.

Security Best Practices

Security checklist

Store client secrets, access tokens, and refresh tokens in a secure server-side secret store.
Do not expose service-level tokens, customer-level tokens, or refresh tokens in browser or mobile code unless that architecture has been reviewed for your integration.
Keep sandbox and production credentials separate.
Refresh tokens before access tokens expire.
Log authentication failures without logging token values.
Treat extId as a durable mapping key, not as a substitute for authentication.
Rotate credentials if a client secret or token may have been exposed.
Use customer-level tokens for User-specific requests and service-level tokens for Partner-level operations.

Troubleshooting

Problem	What to check
`401 Unauthorized`	Confirm the `Authorization` header is present, the token is current, and the token belongs to the same environment as the request.
`403 Forbidden`	Confirm the token level is correct for the endpoint and that the token has access to the requested operation.
Customer request fails with a service-level token	Use the linked customer's access token for customer-level endpoints.
Partner-level request fails with a customer-level token	Use a service-level access token for Partner-level endpoints.
Refresh request fails	Confirm you are using the correct refresh endpoint and the latest stored refresh token.
Recovered token pair does not match stored values	Replace the stored customer token pair with the newly returned pair.

Related API Reference

POST /oauth/token
POST /customer/oauth/token
POST /enterprise/customers/sa/v1/customers/register
POST /enterprise/customers/sa/v1/customers/recreate-tokens