Authentication

Every request carries one API key. Which kind depends on where the request comes from:

Both are created in the dashboard; API keys explains the options each one offers.

Secret key

A secret key authenticates a server. It belongs to one entity, the workspace you see in the dashboard, so the request needs nothing else to say where to work:

curl https://api.hams.ai/outbound-batch/batches \
  -H "X-Secret-Key: $HAMS_SECRET_KEY"

A secret key has a role, WRITER or READER. Readers can list and fetch; writers can also create, update and delete batches and widget configuration. A key can be limited to an IP allowlist (single addresses or CIDR ranges), and calls from any other address get 403. Secret keys are for server-to-server traffic: the API does not answer browser CORS preflights for them, and a secret key that ends up in a page should be revoked and replaced.

Public key

A public key authenticates a browser page or a widget, where a secret cannot be hidden. It only reaches the endpoints under /v1/, which are the chat session and widget configuration calls:

curl -X POST https://api.hams.ai/v1/ai-agents/$AGENT_ID/chat/init \
  -H "X-Public-Key: $HAMS_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Three restrictions keep a public key safe even though it is visible:

• Domains. The request’s Origin (or Referer) must match one of the key’s allowed domains. A public key cannot be created without at least one.
• Scopes. An optional scope list names the operations the key may call, such as chat:init or widget-config:read. A key without a list may call all of them.
• reCAPTCHA. When a reCAPTCHA secret is configured on the key, starting a chat also requires a g-token header carrying a Google reCAPTCHA token, verified against the key’s score threshold.

Which endpoints take which key

Errors