Authentication
Every call carries an API key. The key decides what the call may do.
Send the key
Send the key in the Authorization header of every request, on /api/v1 routes only:
Authorization: Bearer cz_live_…Send it over HTTPS to https://app.contactz.app. Don’t put it in a URL, and don’t paste it into a public repository, a screenshot or a support ticket. A session cookie from the app doesn’t count: a call with no key is a 401, even if you are signed in.
Scopes
You choose a key’s scopes when you create it.
| Scope | What the key can do |
|---|---|
contacts:read | Read your contacts. Also reads your accounts and trigger events. |
contacts:write | Add and change contacts. |
What each call needs
| Call | What it does | Needs |
|---|---|---|
GET /api/v1/openapi.json | This API's OpenAPI document. | No key |
GET /api/v1/me | Who this API key acts for, on which plan, with which scopes. | Any live key |
GET /api/v1/contacts | Find the user's contacts by email, phone or text, or list them. | contacts:read |
POST /api/v1/contacts | Create a contact, treated like one arriving from a sync. | contacts:write |
GET /api/v1/contacts/{id} | One of the user's contacts. | contacts:read |
PATCH /api/v1/contacts/{id} | Change a contact's fields, as the app's edit does. | contacts:write |
GET /api/v1/accounts | The user's linked accounts. | contacts:read |
GET /api/v1/triggers/{event} | A polling trigger — the newest events of one type first. | contacts:read |
A key without the scope a call needs gets a 403 with the code insufficient_scope. A missing key is a 401 with api_key_missing. A key that is not valid, because it was mistyped or revoked, is a 401 with api_key_invalid. See Errors.
Revoke a key
In Settings, then Advanced, choose Revoke next to the key. It stops working at once, and you can’t undo this. Any tool that uses it stops until you give it a new key. We keep only a hash of each key, so we can’t show it to you again.