Management API
The Management API lets your own backend, scripts or CI/CD pipeline manage account settings programmatically, without signing in to the console. You can use it to keep your allowed hostnames in sync with your deployments, and, on accounts where it has been enabled, to look up request history and delete visitor data.
You call it with a management secret, a private credential that you create in the Thumbmark console. If you work in Node.js, the @thumbmarkjs/management SDK wraps the API for you.
Management secrets vs. API keys
Thumbmark uses two different kinds of credentials. Do not mix them up.
| API key | Management secret | |
|---|---|---|
| Used for | Identifying visitors with ThumbmarkJS | Changing account settings through the Management API |
| Where it runs | In the browser | On your server only |
| Is it public? | Yes, it ends up in your page source. Allowed hostnames restrict where it can be used. | No. Anyone holding it can use the permissions it carries. |
| Looks like | Your API key from the console | tmsec_live_... |
A management secret must never appear in browser code, a mobile app, a public repository or a log file. Store it in an environment variable or a secret manager, and revoke it immediately if it might have been exposed.
Base URL
All requests go to:
https://admin-api.thumbmarkjs.com
Every path starts with /v1.
Authentication
Send your management secret as a bearer token in the Authorization header:
Authorization: Bearer tmsec_live_...
Each secret carries one or more permissions (scopes), and each endpoint requires a specific scope. A secret cannot create or revoke other secrets. That is done in the console, see Management secrets.
What you can do
| Endpoint | Description | Required scope |
|---|---|---|
GET /v1/allowed-hostnames | List the account's allowed hostnames | allowed-hostnames:manage |
PUT /v1/allowed-hostnames/{hostname} | Add an allowed hostname | allowed-hostnames:manage |
DELETE /v1/allowed-hostnames/{hostname} | Remove an allowed hostname | allowed-hostnames:manage |
GET /v1/requests/{requestId} | Look up one stored identification request | requests:read |
GET /v1/requests | List a visitor's stored requests | requests:read |
DELETE /v1/visitors/{visitorId} | Delete a visitor's stored request records and visitor entries | visitors:delete |
The three request-history endpoints are available only on accounts where Thumbmark has enabled request history. See Request history.
Quickstart
-
Create a management secret in the console and copy it when it is shown.
-
Put it in an environment variable. Keep it out of your shell history and out of version control.
export THUMBMARK_MANAGEMENT_SECRET='tmsec_live_...' -
Add a hostname, list the hostnames, and remove it again:
# Add (201 the first time, 204 if it is already on the list)
curl -sS -i -X PUT https://admin-api.thumbmarkjs.com/v1/allowed-hostnames/app.example.com \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
# List
curl -sS https://admin-api.thumbmarkjs.com/v1/allowed-hostnames \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
# Remove (204, or 404 if it is not on the list)
curl -sS -i -X DELETE https://admin-api.thumbmarkjs.com/v1/allowed-hostnames/app.example.com \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"The list call returns the hostnames of your account:
{ "items": [{ "hostname": "app.example.com" }, { "hostname": "example.com" }] }
See Allowed hostnames API for the details of each call, including pagination.
Responses and errors
Errors that the API itself produces use a JSON body with a machine-readable code:
{ "error": { "code": "BAD_REQUEST", "message": "Invalid hostname" } }
Some responses can carry an additional details field.
Requests that are rejected before they reach the API return a simpler body instead, for example {"message":"Forbidden"}. Handle the HTTP status code first and treat the body as extra information.
| Status | Meaning |
|---|---|
400 | The request is invalid, for example an invalid hostname or cursor. |
403 | The secret was rejected. See Troubleshooting 403. |
404 | The thing you asked for does not exist, for example a hostname that is not on the list. |
5xx | A temporary problem on the Thumbmark side. Retry with a short delay. |
The request-history endpoints can also answer 429 Too Many Requests with the body {"message":"Too Many Requests"}. Wait and retry later.
Troubleshooting 403
A rejected secret always looks the same: HTTP 403 with {"message":"Forbidden"}. The API deliberately does not tell you which of these is the cause:
- The
Authorizationheader is missing or does not start withBearer. - The token is not a management secret. For example, you used your public API key.
- The secret was revoked, or it was mistyped or truncated.
- The secret does not carry the scope the endpoint requires.
Create a new secret with the right permissions and try again. For 403 responses from the fingerprinting API used by ThumbmarkJS in the browser, see 403 Forbidden.
Next steps
- Management secrets: create, scope, rotate and revoke secrets.
- Allowed hostnames API: list, add and remove hostnames.
- Node.js SDK: use the API from JavaScript and TypeScript.
- Request history: look up stored requests and delete visitor data.