Authentication

Every call needs a key in the header:

curl "https://api.smartchat.marketing/v1/me" -H "Authorization: Bearer $SMARTCHAT_API_KEY"

Without a key the API answers 401 with the code authentication_required.

#Two kinds of credentials

Both go in the same header. The field environment in the answer of GET /me is live. A separate test environment (a sandbox) may follow later; the field is already there.

#Keys belong to the account

• A key belongs to the account, not to the person who made it.
• Only people with the right role create, change or revoke keys, and only in the app. A key can never create or manage keys.
• A revoked key stops working at once (api_key_revoked). An expired key answers with api_key_expired.
• A key can be limited to some IP addresses. From another address the answer is ip_not_allowed.
• Keep keys secret. If a key leaks, revoke it in the app and create a new one.

#Permissions

You choose a level when you create a key. You can also tick single permissions.

A few permissions have their own checkbox, because they reach other people or reveal secrets: newsletters:send, templates:submit, hooks:read_secret, landing:publish and connections:run. The level All includes them, but in the app each of them has its own checkbox that you can untick. The levels Read and Draft never include them.

The level Read changes nothing, with one exception: it can request a contact export (a file with the names, phone numbers and email addresses of your contacts). Read therefore includes the export of personal contact data. Keep that in mind when you hand out a key. The full list, with the calls that need each permission, is on the permissions page.

If a key lacks a permission the answer is 403 insufficient_scope and names the missing permission in required_scope.

#What keys can never do

Some things are only possible in the app. A key or an assistant cannot:

• delete data. The only removals allowed are removing a tag from a contact and unsubscribing a webhook endpoint;
• change the plan, pay, or manage the account (invite or remove people, change roles, delete the account, export everything);
• create or change API keys, connect or disconnect the WhatsApp number, change legal texts or tracking;
• set a contact to "confirmed". Only the contact can confirm.

A call that tries this fails with action_not_allowed.