Allowed hostnames API
Allowed hostnames are the list of websites that may use your public API keys. In the console and in the API keys guide they are also called allowed origins. This is the same list. It belongs to your account and applies to all of its API keys.
- Adding
example.comalso allows its subdomains, such assub.example.com. Wildcards are not supported. - If the list is empty, requests from any origin are allowed.
- An account can have at most 1000 allowed hostnames.
The endpoints on this page let you manage that list from your own backend or CI/CD pipeline, for example to allow a preview environment while it exists.
Authentication and scope
Send a management secret that carries the allowed-hostnames:manage scope as a bearer token. See Authentication. In the console the permission is called Manage allowed hostnames, and it is selected by default when you create a secret.
The examples on this page assume that the secret is in an environment variable:
export THUMBMARK_MANAGEMENT_SECRET='tmsec_live_...'
List allowed hostnames
curl -sS -i https://admin-api.thumbmarkjs.com/v1/allowed-hostnames \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
The response is 200 with the hostnames of the current page:
{
"items": [{ "hostname": "app.example.com" }, { "hostname": "example.com" }],
"nextCursor": "..."
}
nextCursor is present only when there are more pages. See Pagination.
Add an allowed hostname
curl -sS -i -X PUT https://admin-api.thumbmarkjs.com/v1/allowed-hostnames/app.example.com \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
The call needs no request body. It is idempotent:
| Status | Meaning |
|---|---|
201 | The hostname was added. The body is {"hostname":"app.example.com"} with the normalized hostname. |
204 | The hostname was already on the list. There is no body, and nothing changed. |
400 | The hostname is invalid, or adding it would exceed the limit of 1000 hostnames. |
Remove an allowed hostname
curl -sS -i -X DELETE https://admin-api.thumbmarkjs.com/v1/allowed-hostnames/app.example.com \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
| Status | Meaning |
|---|---|
204 | The hostname was on the list and has been removed. |
404 | The hostname was not on the list. |
400 | The hostname is invalid. |
Removing a hostname that is not on the list is an error, not a silent success. If your automation should treat "already gone" as success, accept 404 yourself. The SDK has an idempotent option for this.
Pagination
Results are returned one page at a time, with the hostnames in each page sorted alphabetically. To read the next page, pass the nextCursor value from the previous response back unchanged as the cursor query parameter:
curl -sS "https://admin-api.thumbmarkjs.com/v1/allowed-hostnames?cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $THUMBMARK_MANAGEMENT_SECRET"
Keep going until a response has no nextCursor. Treat the cursor as an opaque string: do not parse or build one yourself. An invalid cursor is answered with 400. A single page can already hold all of your hostnames, so do not assume that nextCursor is always present or always absent.
Hostname rules
Put the hostname in the URL path. If it contains special characters, URL-encode it.
- Use a bare hostname such as
app.example.com. If you pass a URL orhost:port, the scheme, port and path are stripped before the hostname is stored or looked up. - Hostnames are converted to lowercase.
localhostis accepted, which is handy for local development.- IP addresses are rejected.
- Wildcards such as
*.example.comare rejected. Add the parent domain instead, which already covers its subdomains. - Only
httpandhttpsURLs are accepted. Other schemes are rejected. - Each part of the hostname, between the dots, must be 1 to 63 characters of letters, digits and hyphens, and cannot start or end with a hyphen.
Errors
Application errors use a JSON body such as the following. See Responses and errors.
{ "error": { "code": "NOT_FOUND", "message": "Hostname \"x.example.com\" not found" } }
A 403 with the body {"message":"Forbidden"} means that the secret was rejected. See Troubleshooting 403.
When changes take effect
Your changes are stored immediately, but Thumbmark caches authorization results for a short time. A change to the list can therefore take a couple of minutes before it applies to requests from browsers. See Authorization caching.
Next steps
- Node.js SDK: the same operations from JavaScript and TypeScript.
- Management secrets: create and manage the credentials these calls need.