Skip to main content

Management secrets

A management secret is a bearer token that authorizes programmatic access to the Thumbmark Management API, for example to update your allowed hostnames from a CI/CD pipeline. Secrets are scoped to specific operations, they do not expire, and you can revoke them at any time.

A management secret is not the same thing as your public API key. See Management secrets vs. API keys.

Secrets start with tmsec_live_. The console shows them in masked form, as tmsec_live_… followed by the last four characters.

Server-side only

Treat a management secret like a password. Never put it in browser code, a mobile app, a public repository or a log file.

Create a management secret​

Management secrets are created in the console, not through a management secret.

  1. Sign in and open the Management API page of the console. The page is headed Management API and has a Management Secrets card.
  2. Click Create your first management secret. If you already have secrets, the button is called Create new secret.
  3. In the Create Management Secret dialog, optionally enter a Name (optional) of up to 64 characters, such as ci-pipeline, to tell your secrets apart later.
  4. Under Permissions, choose what the secret may do. Manage allowed hostnames is selected by default, and you must select at least one permission.
  5. Click Create.
  6. The Your New Management Secret dialog shows the secret. This is the only time you will see it: Thumbmark stores only a one-way hash of the secret, so it cannot be shown again. Click Copy to Clipboard, store it somewhere safe, and then click I've saved my secret.

If you lose a secret, revoke it and create a new one.

The secret list shows each secret's name (or "Unnamed"), the masked secret, its permissions, when it was created and when it was last used, or Never used. The last-used time is approximate. It is refreshed at most about once an hour.

Permissions (scopes)​

Each secret carries one or more scopes. An endpoint accepts a secret only if the secret carries the scope that endpoint needs. A secret can do only what its scopes allow. For example, a secret with allowed-hostnames:manage cannot manage API keys, webhooks or billing.

Console labelScopeAllows
Manage allowed hostnamesallowed-hostnames:manageList, add and remove allowed hostnames.
Read request historyrequests:readLook up a request by its ID and list a visitor's requests. See Request history.
Delete visitor datavisitors:deleteDelete a visitor's stored request records and visitor entries. See Request history.

requests:read and visitors:delete are offered only to account admins, and only on accounts where Thumbmark has enabled request history. The permissions you can select in the console therefore depend on your account and your role.

You can combine permissions in one secret, but we recommend one secret per integration and, for request history, one secret per permission. That way a leaked secret can do as little as possible.

Active secret limit​

An account can hold at most 10 active management secrets at the same time. This is the current value. The limit may change, so do not hard-code it in your tooling. The Management Secrets card in the console always shows the current limit.

  • The limit counts every active secret on the account, including secrets created by your teammates that you may not see in your own list.
  • Revoked secrets do not count towards the limit.
  • When you have reached the limit, the Create new secret button is disabled in the console. If you try to create one anyway, the request is rejected (HTTP 409).
  • To free a slot, revoke a secret you no longer use. If the secrets that fill the limit are not visible to you, ask an account admin to revoke one.

Store a secret safely​

  • Keep the secret in an environment variable or in your CI/CD system's secret store, for example THUMBMARK_MANAGEMENT_SECRET. Read it from there at runtime.
  • Do not commit it, paste it into tickets or chat, or print it in build logs.
  • Never include it in code that runs in a browser.
  • Use a separate secret for each integration, so you can revoke one without breaking the others.
  • Prefer a secret manager over a plain environment variable where one is available.
  • Send the secret only in the Authorization header, never in a URL or query string.
  • Do not log request-history responses. They can contain personal data such as an IP address.
  • Give the visitors:delete permission only to the service that handles erasure requests.

Revoke a secret​

Revoke a secret when you no longer need it, or immediately if it might have been exposed.

  1. Open the Management API page of the console.
  2. Click Revoke next to the secret.
  3. In the Revoke Secret dialog, confirm with Revoke Secret. Any automation using this secret stops working immediately, and this cannot be undone.

A revoked secret is rejected on its next request with 403 (see Troubleshooting 403). It disappears from the list and no longer counts towards the limit.

Rotate a secret​

Management secrets have no expiry and are not rotated automatically. To replace one without downtime:

  1. Create a new secret with the same permissions. If you are at the limit, revoke a secret you do not use first.
  2. Deploy the new secret to your pipeline or server.
  3. Check in the console that the new secret shows a Last used time. Remember that this time is approximate.
  4. Revoke the old secret.

Next steps​