Authentication and access
This page explains the authorization model behind the 401 and 403 responses of the TOM External API: what the API key represents, which modules each operation needs, how survey access works and what to expect when a key is wrong.
1. The key is the user
Every request carries your API key in the X-API-Key header. The key identifies one TOM user, and every call runs with that user's permissions:
- There is no OAuth flow and there are no scopes. The key is the only credential.
- Only the surveys contracted for that user can be used.
- Calculations need the application module that matches them in the user's profile (section 2).
- Workspaces, targets, user variables and optimization jobs belong to the user. A workspace is visible to its owner and to the users it is shared with.
- A
jobIdthat belongs to another user is answered as if it did not exist (404JOB_NOT_FOUND): the two cases cannot be told apart.
Because the key is the user, what you create through the API (workspaces, targets, optimization jobs) also appears for that user in the TOM web application, and the tabulations, Reach tables, targets and user variables that the user saves there can be read through the API.
2. Licensed modules
TOM licenses its calculation features as application modules. A call that needs a module the user does not have is rejected with 403 and the error code AE_ERR_408. The same response is returned when the user's modules cannot be resolved: the API denies access when it cannot confirm it.
| Module | Operations that need it |
|---|---|
| Tabulation | GET /api/v2/statistics with tableType=TABULATION (the default). POST /api/v2/table/{surveyCode} and POST /api/v2/table/{surveyCode}/html with tableType TABULATION. |
| Study | GET /api/v2/statistics with any other tableType. Table calculations with tableType TREND, BREAKDOWN_CARRIERS or DUPLICATIONS. Rankings, evaluations (and saving them), response curves and the three optimization operations. |
| Reach | GET /api/v2/survey/{surveyCode}/reach-capabilities. POST /api/v2/reach/{surveyCode}. Table calculations with tableType REACH_TABLE, REACH_DUPLICATION or REACH_TREND. |
| None | Listing surveys and workspaces, the variables and carriers lists, the tree queries, user variables, targets, saved tabulations and workspace elements, creating workspaces, adding surveys and creating or updating targets. |
The table type of a table request decides the module, so one endpoint can need different modules depending on the body you send.
3. Survey access
A user can use only the surveys that are enabled in their TOM profile. How the API reports a survey that the user cannot use depends on the endpoint:
| Endpoints | Status and errorCode | Meaning |
|---|---|---|
| Variables list, carriers list and the two tree queries | 403 AE_ERR_415 | The survey is not available to the user: not contracted, disabled, being loaded or non-existent. The answer is the same in every case. |
| The calculation endpoints, saved tabulations and the rest of the survey-scoped endpoints | 401 SO_ERR_203 | The survey is not in the user's profile, or it does not exist. |
| The same endpoints | 400 SO_ERR_201 | The survey is disabled or being loaded. |
Do not build logic that depends on telling these cases apart. Read the survey list (GET /api/v2/users/surveys) to know what the user can use, and refresh it when a survey-scoped call reports that a survey is not available. The list leaves out surveys that are being loaded or are disabled, so it can change between calls.
A workspace can keep surveys that the user can no longer query, for example one that is no longer contracted. Check the surveys of a workspace against the survey list before you use one.
4. Unknown, revoked or missing keys
| Situation | Typical response |
|---|---|
The X-API-Key header is missing | 401 E401 on every endpoint. |
| The key does not identify a TOM user (unknown or revoked) | The response depends on the endpoint. You can get 400 TW_ERR_500 (for example on the survey and workspace lists), 403 AE_ERR_408 on the endpoints that check modules, or the code returned by the platform. |
Treat any of these responses on a key that worked before as "check the key", and do not retry the same request in a loop. To obtain, rotate or revoke a key, contact your TOM platform representative.
5. Propagation delays
The API keeps the modules and the survey access of a user for a while, so that it does not have to ask for them on every call. After a change in the user's profile (a new module, a new survey, a removed survey), allow up to an hour before you expect the API to reflect it.
6. Security recommendations
- Keep the key on your server. Never put it in a URL, in browser or mobile code, in screenshots or in logs.
- Read it from an environment variable or from a secret store.
- Do not share one key between unrelated integrations: because the key is the user, whoever has it sees everything that user sees and can create and change what that user owns.
- Never include the key in a support request. Send the UTC time of the call, the endpoint and the
errorCodeinstead. - If a key may have been exposed, ask your TOM platform representative to replace it.