# Authentication and scopes

> Create an API key, choose its scopes and role, act as a teammate, and keep keys safe.

- Canonical page: https://synconone.com/docs/api-authentication
- Section: Developers
- Updated: 2026-10-22

Every request carries an API key. A key is a deliberate, narrow grant: it can do only what its scopes and its role allow, and every change it makes is recorded against it.

## Create a key

1. Open Settings → API. Only owners and admins manage keys.
2. Name the key for what it is used for, such as "Order sync".
3. Choose its scopes, its role, an optional expiry and its requests-per-minute limit.
4. Copy the key. It starts with `sk_live_`. We store only a hash, so a lost key cannot be recovered: revoke it and make another.

```bash
curl https://synconone.com/api/v1/pipelines -H "Authorization: Bearer sk_live_YOUR_KEY"
```

A missing, wrong, revoked or expired key answers `401`. A workspace that is not on Pro or Enterprise answers `403` to every key.

## Scopes

A scope names a kind of access. A write scope includes the matching read. A call that needs a scope the key lacks answers `403` and names the scope it needed.

| Scope | Allows |
| --- | --- |
| `people:read` | Read customers |
| `people:write` | Create and change customers |
| `companies:read` | Read companies |
| `companies:write` | Create and change companies |
| `leads:read` | Read leads |
| `leads:write` | Create and change leads |
| `opportunities:read` | Read opportunities |
| `opportunities:write` | Create and change opportunities |
| `tasks:read` | Read tasks |
| `tasks:write` | Create and change tasks |
| `notes:read` | Read notes |
| `notes:write` | Create and change notes |
| `records:read` | Read custom object records |
| `records:write` | Create and change custom object records |
| `pipelines:read` | Read pipelines and stages |
| `evidence:read` | Read evidence |
| `reports:read` | Run reports |
| `webhooks:read` | Read webhook endpoints |
| `webhooks:write` | Manage webhook endpoints |
| `team:read` | Read teammates |
| `tickets:read` | Read support tickets |
| `tickets:write` | Open and change support tickets |
| `meetings:read` | Read meetings |
| `meetings:write` | Schedule, change and cancel meetings |
| `conversations:read` | Read live chat conversations |
| `conversations:write` | Reply in, assign and manage live chat conversations |

## Roles and acting as a person

Scopes are not the only gate. Every key also has a role, and a call must be something that role could do in the app. A key with the viewer role and a write scope can still not write, because a viewer cannot write in the app either. Keys can hold the admin, manager, member or viewer role, never owner.

A key can also **act as** one teammate. It then sees exactly what that teammate sees: their role, their teams and which records are visible to them. Fields hidden from that role are absent from responses, and records they cannot see answer `404`, as if they did not exist. Use this for a key that belongs to one person's automation.

Replies sent in the live chat inbox and meetings scheduled through the API are made as the person the key stands for: its creator, or the teammate it acts as.

## Keeping keys safe

- One key per job, with the fewest scopes it needs. Revoke a key the day it is not.
- Keep keys in environment variables or a secrets manager, never in a repository, a browser or a mobile app. A browser is not a safe place for a key.
- Set an expiry on keys given to contractors or trials.
- Every change a key makes is recorded with the key's name and prefix, so what a leaked key did can be traced.

> **If a key leaks** Revoke it in Settings → API straight away. Revoking takes effect on the next request. Then make a new key and review what the old one could reach.