Truform Captcha

Site keys and security

Domains, subdomains, and optional IP allowlists for each Truform site key.

Each Truform subscription is a service in your Syndaq client area. Every protected website uses its own site key (public and secret pair). Site keys are listed on your service dashboard. Open Manage on a key to change its domain, view credentials, or configure IP restrictions.

How site keys map to domains

When you order Truform, you provide a primary domain. That domain becomes the first site key on the service. You can add more site keys on the same subscription if your plan allows multiple domains.

Each site key is locked to one root domain. Truform automatically allows that domain and all of its subdomains. For example, a key for example.com also accepts www.example.com, app.example.com, and any other hostname that ends with .example.com.

Requests from any other domain are rejected. This applies to browser traffic (challenge and verify) and is enforced using the page hostname and standard browser origin headers.

Changing a domain

In the client area, go to Services, open your Truform service, choose Manage on the site key, and update the domain under Protected domain. Save the change before deploying the updated site key on your site.

Public and secret keys per site key

Every site key has:

CredentialPrefixWhere it belongs
Public site keytf_pub_HTML, JavaScript, and browser API calls
Secret keytf_sec_Your backend only, for siteverify

Use the public key from the site key row that matches the domain you are protecting. Do not reuse one site key across unrelated domains.

IP restrictions (optional)

IP restrictions are optional and configured per site key in the client area under IP restrictions.

When IP restrictions are disabled (the default), Truform does not filter by caller IP address.

When IP restrictions are enabled, every API request authenticated with that site key must come from an allowed IPv4 or IPv6 address. This includes:

  • Browser puzzle requests (/v1/truform/challenge)
  • Managed verification (/v1/truform/managed)
  • Browser verification (/v1/truform/verify)
  • Server side token checks (/v1/truform/siteverify)

If the caller IP is not on the allowlist, the API responds with HTTP 403 and error code ip_not_allowed.

Allowed IP formats

You can enter one or more entries, separated by commas or new lines:

FormatExampleMeaning
Single IPv4203.0.113.10One server or egress IP
IPv4 CIDR198.51.100.0/24A range of IPv4 addresses
Single IPv62001:db8::1One IPv6 server or egress address
IPv6 CIDR2001:db8::/32A range of IPv6 addresses

IPv4 and IPv6 entries can be mixed in the same allowlist.

When you enable IP restrictions, you must add at least one valid entry. An empty allowlist is not permitted while restrictions are on.

When to use IP restrictions

IP restrictions are useful when:

  • Your backend calls siteverify from a fixed set of servers or a known egress IP
  • You want an extra layer of protection on top of domain binding and secret key auth
  • You operate behind a corporate firewall or a single cloud region with stable outbound IPs

They are not a substitute for domain binding. Browser visitors still load the widget from your allowed domain. IP restrictions mainly protect server side and API traffic tied to your keys.

Siteverify and outbound IP

If your application server calls siteverify, enable IP restrictions only after you know the outbound IP your server uses to reach api.syndaq.com. That IP (or CIDR) must be on the allowlist or verification will fail with ip_not_allowed.

If your host uses dynamic IPs or many egress paths, leave IP restrictions disabled or use a CIDR that covers your provider range.

Client area workflow

  1. Sign in to the Syndaq client area and open Services.
  2. Select your Truform service to see usage stats and the site key table.
  3. Use Manage on a key to edit the domain, copy keys, rotate the secret, or set IP rules.
  4. Use Analytics on a key to review request volume and response codes.
  5. Configure Webhooks on the service page for quota threshold and exceeded alerts.

Verification mode (Developer and Enterprise)

Per-key policies include Verification mode:

ModeBehavior
Interactive (default)Visitors complete a puzzle. Same as all releases before API 2.1.0.
ManagedLow-risk visitors verify without a puzzle. Others receive a puzzle automatically.

Managed mode also exposes a Managed risk threshold (0–100). Visitors at or above the threshold complete a puzzle instead of passing silently.

When you switch to Managed mode, update your embed snippet from the Integrate tab to include data-mode="managed". Until you deploy the new snippet, visitors continue to use Interactive verification even if the site key is set to Managed.

Monthly quota

Monthly quota applies to the whole subscription, not each site key individually. All site keys on a service share one quota pool. Response headers X-Quota-* and the Usage API reflect the shared count.