Skip to main content

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.com also allows its subdomains, such as sub.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:

StatusMeaning
201The hostname was added. The body is {"hostname":"app.example.com"} with the normalized hostname.
204The hostname was already on the list. There is no body, and nothing changed.
400The 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"
StatusMeaning
204The hostname was on the list and has been removed.
404The hostname was not on the list.
400The 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 or host:port, the scheme, port and path are stripped before the hostname is stored or looked up.
  • Hostnames are converted to lowercase.
  • localhost is accepted, which is handy for local development.
  • IP addresses are rejected.
  • Wildcards such as *.example.com are rejected. Add the parent domain instead, which already covers its subdomains.
  • Only http and https URLs 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​