Authentication

Every request to /public/v1/* authenticates with the X-API-Key header — never Authorization: Bearer, and never a session cookie:

curl https://api.aymaragents.com/public/v1/leads \
  -H "X-API-Key: aa_YOUR_FULL_KEY"

A key is shown in full once, when you create it (guide API keys, section 4); from then on, any listing shows only its prefix (aa_xxxxxxxx…).

Scope catalog

Every resource has two independent scopes — read, and manage (create/update). A key missing the exact scope an endpoint requires gets 403 PERMISSION_DENIED, even with the rest of its permissions intact:

Resource	Read	Manage
Leads	tenant:leads.read	tenant:leads.manage
Contacts	tenant:contacts.read	tenant:contacts.manage
Conversations	tenant:conversations.read	tenant:conversations.manage
Appointments	tenant:appointments.read	tenant:appointments.manage
Tickets	tenant:tickets.read	tenant:tickets.manage

GET /public/v1/me requires no scope of its own — just a valid key on a plan-eligible tenant (see Plans and limits) — and returns your key’s EFFECTIVE scope set, so you never have to guess it:

curl https://api.aymaragents.com/public/v1/me -H "X-API-Key: aa_YOUR_FULL_KEY"

Check the scopes you need in the “Customize” step when creating the key (API keys guide, section 7) — that selection is sealed at that point, it isn’t extended later: adding a scope means revoking the key and creating a new one.

What a key can never do

• Anything outside the 5 resources above. There is no public route for billing, team, settings, integrations, AI agents, or admin — no matter the key’s scope, those actions simply have no endpoint under /public/v1.
• See or touch another tenant’s data. A key is bound to a single tenant; an id from another tenant on any route returns 404, indistinguishable from “does not exist” (never 403, which would confirm it exists).
• Log in to the Platform’s web interface — the key authenticates API calls, not a person’s login.

Rotating a key

There is no atomic rotation endpoint today. To rotate a key: create a new one with the same scopes, update the secret in your integration, and then revoke the old one (API keys guide, section 9) — there’s a short window with both active, no instant invalidation of the old one when the new one is created.

Allowed origins

allowed_origins (configurable when creating the key) is a defense against browser-based abuse — it’s only checked when the request carries an Origin header. A server-to-server call, this API’s main use case, usually doesn’t send one and passes through even with a restricted list — don’t treat it as the authentication mechanism, just an extra layer.