# Authentication

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

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

```http
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

```json
// 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": "..." }
```