API: Authentication
The Insight API uses token-based authentication. Every API request must include a valid token to identify your organization and authorize access. This is a standard approach used by most modern APIs — if you've worked with any other API before, this will feel familiar.
How it works
- An administrator creates an API token in Insight
- The token is included in every API request as a header
- Insight verifies the token and checks that it has permission for the requested data
- If valid, the data is returned; if not, you receive an error
For developers
Obtaining a token
Contact your Brilliant representative to request an API token. They will configure the token with the appropriate permissions for your integration needs and provide it to you securely.
Using the token
Include the token in the Authorization header of every request:
Authorization: Bearer YOUR_API_TOKEN
Token permissions
Each token has specific permissions that control what data it can access:
| Permission | Grants access to |
|---|---|
| Organization | GET /api/public/groups |
| Survey | GET /api/public/surveys |
| Results | GET /api/public/surveys/{id}/results, GET /api/public/indexes, GET /api/public/questions |
A token without the required permission will receive a 403 Forbidden response.
Security best practices
- Never commit tokens to source control — use environment variables or a secrets manager
- Rotate tokens periodically — revoke old tokens and create new ones
- Use least privilege — only grant the permissions each integration actually needs
- Use HTTPS — all API calls must be made over HTTPS
Error responses
| Status | Meaning | What to do |
|---|---|---|
401 Unauthorized |
Token is missing or malformed | Check the Authorization header format |
403 Forbidden |
Token is valid but lacks permission | Verify the token has the required permission in Insight |