Skip to main content

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 keyManagement secret
Used forIdentifying visitors with ThumbmarkJSChanging account settings through the Management API
Where it runsIn the browserOn 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 likeYour API key from the consoletmsec_live_...
Keep management secrets on the server

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​

EndpointDescriptionRequired scope
GET /v1/allowed-hostnamesList the account's allowed hostnamesallowed-hostnames:manage
PUT /v1/allowed-hostnames/{hostname}Add an allowed hostnameallowed-hostnames:manage
DELETE /v1/allowed-hostnames/{hostname}Remove an allowed hostnameallowed-hostnames:manage
GET /v1/requests/{requestId}Look up one stored identification requestrequests:read
GET /v1/requestsList a visitor's stored requestsrequests:read
DELETE /v1/visitors/{visitorId}Delete a visitor's stored request records and visitor entriesvisitors:delete

The three request-history endpoints are available only on accounts where Thumbmark has enabled request history. See Request history.

Quickstart​

  1. Create a management secret in the console and copy it when it is shown.

  2. Put it in an environment variable. Keep it out of your shell history and out of version control.

    export THUMBMARK_MANAGEMENT_SECRET='tmsec_live_...'
  3. 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.

StatusMeaning
400The request is invalid, for example an invalid hostname or cursor.
403The secret was rejected. See Troubleshooting 403.
404The thing you asked for does not exist, for example a hostname that is not on the list.
5xxA 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 Authorization header is missing or does not start with Bearer .
  • 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​