Authentication

This article covers how to obtain your API token and include it correctly in every request to the Indivd API. Authentication is required before you can call any endpoint.

Included in: ✓ Indivd Basic    ✓ Indivd Pro    ✓ Indivd Complete

Related articles

• Indivd API
• Make your first API call
• How to query visitor data

This article contains the following topics:

• How authentication works
• Request your token
• Token scope
• Authenticate a request
• Security practices
• Error reference
• Troubleshooting

How authentication works

The Indivd API uses token-based authentication. Every request must include a static API token in the Authorization HTTP header. There are no session tokens, no OAuth flows, and no expiring credentials. Your token is valid until Indivd rotates or revokes it.

Tokens are not generated self-serve from the Indivd platform. They are issued by Indivd and scoped to specific locations or organisations at the time of creation.

Request your token

To request an API token:

1. Contact your Indivd account contact or email support@indivd.com.
2. Specify which locations or organisations the token should cover.
3. Store the token securely once received. Treat it as a password.

Note: Do not include your token in client-side code, version control repositories, or any shared document. If you believe a token has been exposed, contact support@indivd.com immediately to request a replacement.

Token scope

A token is scoped to the locations and organisations specified when it was issued. A single token can cover multiple locations across one or more organisations. Requests for data outside that scope return an empty result set, not an error. If you need access to additional locations after your token is issued, contact your Indivd account contact to have the token's scope updated.

To confirm which locations your token has access to, call the locations filter endpoint after authenticating:

curl --location --request GET \
'https://api.indivd.com/filters/locations' \
--header 'Authorization: Token [your-token-here]' \
--header 'Content-Type: application/json'

The response lists every location accessible to your token. If a location you expect to see is missing, contact your Indivd account contact.

Authenticate a request

Every request to the Indivd API must include a token in the Authorization header using the following format:

Authorization: Token [your-token-here]

The header name is case-sensitive. The value must start with Token followed by a single space and then your token. No other formats are accepted.

Example authenticated request using curl:

curl --location --request GET \
'https://api.indivd.com/filters/locations' \
--header 'Authorization: Token [your-token-here]' \
--header 'Content-Type: application/json'

Replace [your-token-here] with the token provided by Indivd. All sample requests throughout the API documentation use this placeholder.

Security practices

Follow these practices to keep your token secure:

• Store the token in an environment variable or a secrets manager, not in source code.
• Never commit the token to a version control repository, including private repositories.
• Never share the token in Slack messages, emails, or shared documents.
• Do not include the token in URLs or query string parameters.
• Rotate the token if you suspect it has been exposed. Contact support@indivd.com to request rotation.

Error reference

Authentication failures return standard HTTP error codes. No additional JSON body is returned with authentication errors.

Note: A 403 response is distinct from an empty result set. If your token has access to a location but no data matches your query parameters, the API returns a 200 response with an empty insights array, not a 403.

Troubleshooting

Note: If your request returns a 401 Unauthorized error, check the following: the header name is exactly Authorization, the value starts with Token followed by a single space and your token, and the token itself has not been truncated, modified, or wrapped in quotation marks.

Note: If your request returns a 403 Forbidden error and you believe your token should have access to the resource, contact your Indivd account contact to verify the token's scope.

Note: If requests are failing unexpectedly and your token and headers are correct, check indivd.statuspage.io to confirm all platform components are operational before investigating further.