Embed endpoints and allowed domains

The embed endpoints are the browser-facing calls that the embed loader and hosted pages make. You can also call them from your own front end. They use your public key and only answer pages on your allowed domains.

Before you start

You need:

• Your public key. It starts with pk_. The Go live page in the portal shows it, with the embed host.
• Your page's origin in your list of allowed domains. Add it in the portal under Allowed domains.

A public key isn't a secret, because it appears in every embed snippet. The allowed-domain check is what stops other sites from using it. Never send a secret key to these endpoints. They ignore the Authorization header.

Minimal example

This request lists the calculators your public key can use. The Origin header stands in for the page that makes the call. Use an origin from your allowed domains.

export AZTEC_EMBED_HOST="<your embed host>"
export AZTEC_PUBLIC_KEY="<your public key>"

curl -sS -i "https://$AZTEC_EMBED_HOST/embed/v1/$AZTEC_PUBLIC_KEY/calculators" \
  -H "Origin: https://www.example.com"

When your list includes the origin, the response is 200 and carries Access-Control-Allow-Origin: https://www.example.com. The body has an items array of calculators and a cobrand object with your branding, call-to-action buttons, disclaimer and locales.

Options

All paths start with /embed/v1/{publicKey}.

Request	Returns
GET /calculators	The calculators your cobrand can use, with the cobrand's presentation
GET /calculators/{calculatorId}	One calculator's definition: inputs, outputs, labels, branding and engineVersion
POST /calculators/{calculatorId}/calculate	The results of a calculation, with engineVersion
POST /events	Records a call-to-action event. The Aztec-Calcs renderer sends it.

The calculatorId is the calculator key. The two GET requests take an optional locale query parameter. The calculate request takes the same JSON body as the REST API: inputs and an optional locale. An unsupported locale falls back to your cobrand's default instead of failing, and validation messages come back in the request locale.

The allowed-domain check

Every request runs these steps in order: find the cobrand by key, check the domain, check the calculator, validate, calculate.

• The domain comes from the Origin header. Without one, it comes from the host of the Referer header. Paths and query strings are never kept.
• Compare hosts without case, port and trailing dot.
• An entry matches an exact host, or a wildcard such as *.example.com. A wildcard matches subdomains and never the bare domain.
• Only https pages pass. The one exception is http on localhost or 127.0.0.1, and only when you listed that host.
• An empty list allows no pages except the Aztec-Calcs hosted pages and your own serving custom domain.

An allowed domain gets Access-Control-Allow-Origin with its exact origin. The service never sends * and never uses credentials. A preflight OPTIONS request gets the same check, and an allowed one answers 204 with Access-Control-Allow-Methods, Access-Control-Allow-Headers: Content-Type and Access-Control-Max-Age: 600.

Errors and limits

Errors use application/problem+json with type, title, status, detail, instance, code and traceId.

Status	code	Meaning
404	cobrand_not_found	No cobrand has this key. The response is the same for every unknown key.
403	origin_not_allowed	The domain isn't allowed. The rejectedHost field names the host the service saw.
404	calculator_not_found	No active calculator has this id.
403	calculator_not_entitled	Your cobrand doesn't have this calculator's group.
413	payload_too_large	The body is over 32 KB.
429	rate_limited	You went over your limit. Wait the Retry-After seconds.
400 or 422	validation_failed	An input is invalid. The errors array lists the fields. A body that isn't JSON gives the field body with the code malformed_json.
400	invalid_beacon	The event body isn't valid.
503	service_unavailable	The service can't answer right now. Retry-After is 10 seconds.
503	catalog_unavailable	The calculator list can't be read. Retry-After is 10 seconds. The cobrand field holds your branding, so a page can still show it.
500	engine_fault	The calculation failed.

Validation errors use the same field codes as the REST API. Business calculators answer 400, and all others answer 422.

Limit	Value
Calculate body	32 KB
Event body	1 KB
Request rate	1,200 requests a minute for each cobrand. See Rate limits.
Caching	A 200 to a GET that an Origin header allowed is cacheable for 300 seconds. Every other response has Cache-Control: no-store. All responses vary on Origin.

Related API reference

• Calculate
• Get calculator schema