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"
}

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
}

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"
}

After a successful refresh, 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
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": []
}

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}"
}

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"
  }
]

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
POST /enterprise/customers/sa/v1/customers/recreate-tokens