Skip to main content

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 jobId that belongs to another user is answered as if it did not exist (404 JOB_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.

ModuleOperations that need it
TabulationGET /api/v2/statistics with tableType=TABULATION (the default). POST /api/v2/table/{surveyCode} and POST /api/v2/table/{surveyCode}/html with tableType TABULATION.
StudyGET /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.
ReachGET /api/v2/survey/{surveyCode}/reach-capabilities. POST /api/v2/reach/{surveyCode}. Table calculations with tableType REACH_TABLE, REACH_DUPLICATION or REACH_TREND.
NoneListing 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:

EndpointsStatus and errorCodeMeaning
Variables list, carriers list and the two tree queries403 AE_ERR_415The 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 endpoints401 SO_ERR_203The survey is not in the user's profile, or it does not exist.
The same endpoints400 SO_ERR_201The 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​

SituationTypical response
The X-API-Key header is missing401 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 errorCode instead.
  • If a key may have been exposed, ask your TOM platform representative to replace it.