# Authentication

> How to sign in to the API with a key, which permissions exist, what keys can never do, and how keys differ from the OAuth tokens of the MCP server.

Last updated: 2026-10-30. Source: https://docs.smartchat.marketing/en/authentication/

Every call needs a key in the header:

```bash run
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`](https://docs.smartchat.marketing/en/errors/#authentication_required).

## Two kinds of credentials

| | API key | OAuth access token |
|---|---|---|
| Starts with | `sc_` | `sc_at_` |
| Made for | Your own software, Zapier, Make, n8n | AI assistants that connect to the [MCP server](https://docs.smartchat.marketing/en/mcp/) |
| Created | In the SmartChat app | By the assistant, after you agree on a consent page |
| Used at | The REST API and the MCP server | Mainly the MCP server |

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`](https://docs.smartchat.marketing/en/errors/#api_key_revoked)). An expired key answers with [`api_key_expired`](https://docs.smartchat.marketing/en/errors/#api_key_expired).
- A key can be limited to some IP addresses. From another address the answer is [`ip_not_allowed`](https://docs.smartchat.marketing/en/errors/#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.

| Level | What it means | Permissions |
|---|---|---|
| Read | Read everything that is not secret. Changes nothing, with one exception: it can request a contact export, which creates a file with personal data. | 17 |
| Draft | Everything in Read, plus create and change drafts. Nothing reaches other people. | 25 |
| All | Everything except deleting and the plan. It includes the permissions with their own checkbox; in the app you can untick them. | 38 |

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](https://docs.smartchat.marketing/en/api/permissions/).

If a key lacks a permission the answer is 403 [`insufficient_scope`](https://docs.smartchat.marketing/en/errors/#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`](https://docs.smartchat.marketing/en/errors/#action_not_allowed).

> **Warning** Keys of the earlier SmartChat API are not valid any more. Create new keys and connect assistants again.