Authentication

Keys, permissions (scopes) and how to keep a key safe.

For AIDownload .md All docs as one Markdown file llms.txt (index)llms-full.txt (all docs)OpenAPI (JSON)

Every call carries an API key in the Authorization header. A key cannot be sent in the body or the query string.

Authorization: Bearer hzk_your_key_here

Permissions (scopes)

Give each key only what it needs. A permission is a kind of record and a mode: <type>.read or <type>.write. A call without the right permission answers 403.

Permission	Allows
`contacts.read`	Read contacts: list, find, read one, list properties
`contacts.write`	Create and change contacts
`companies.read`	Read companies: list, find, read one, list properties
`companies.write`	Create and change companies
`deals.read`	Read deals: list, find, read one, list properties
`deals.write`	Create and change deals
`tickets.read`	Read tickets: list, find, read one, list properties
`tickets.write`	Create and change tickets
`products.read`	Read products: list, find, read one, list properties
`products.write`	Create and change products
`orders.read`	Read orders: list, find, read one, list properties
`orders.write`	Create and change orders
`calls.read`	Read calls: list, find, read one, list properties
`calls.write`	Create and change calls

Good practice

Keep keys on your server. Never put one in a web page, a mobile app or a public repository.
Make a separate key for every system, with the smallest set of permissions. Start with read only.
Revoke a key at any time under Settings > Developers; the last calls of each key are listed there.
A key can have an expiry date and a list of allowed IP addresses.
Wrong keys are limited per address, so guessing does not work.

Authentication errors

// 401: no key, a wrong key, or a revoked or expired key
{ "statusCode": 401, "message": "..." }

// 403: the key is valid but lacks the permission (or the address is not allowed)
{ "statusCode": 403, "message": "..." }