# Autentizace

> Autentizujte požadavky na API bearer tokenem s API klíčem nebo přístupovým tokenem OAuth, zvolte oprávnění full, nebo sending, omezte klíče na doménu a ošetřete chyby autentizace.

Každý požadavek na API Emailitu musí v hlavičce `Authorization` nést přístupový údaj. Tato stránka popisuje dva druhy přístupových údajů (API klíče a přístupové tokeny OAuth), co které oprávnění umožňuje a všechny chyby autentizace, které můžete dostat.

## API klíče

API klíč patří do jednoho workspace a každý požadavek, který s ním pošlete, pracuje s tímto workspace. Klíče vypadají takto:

```text
secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG
```

Tedy `secret_` a za ním 32 písmen a číslic. Klíče vytvořené před zavedením formátu `secret_` předponu nemají a fungují dál.

Klíče vytvoříte ve webovém rozhraní v sekci **Email API → API Keys**, nebo přes endpoint [Vytvoření API klíče](/cs/docs/api-reference/api-keys/create/). Tajný údaj se zobrazí jen jednou, když klíč vytvoříte nebo [znovu vygenerujete](/cs/docs/api-reference/api-keys/regenerate/), proto ho hned uložte. Jak klíče spravovat, popisuje stránka [API klíče](/cs/docs/developers/api-keys/).

Stejné klíče fungují jako heslo pro SMTP u [SMTP relay](/cs/docs/smtp/settings/).

## Posílejte klíč s každým požadavkem

V hlavičce `Authorization` použijte schéma `Bearer`. API nepřijímá klíče v řetězci dotazu ani v těle požadavku.

**cURL**

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()
```

SDK tuto hlavičku nastaví za vás, když klientovi předáte klíč.

## Rozsahy oprávnění

Každý klíč má jedno ze dvou oprávnění. Zvolíte ho při vytvoření klíče a později ho nelze změnit.

| Oprávnění | Co může volat | K čemu slouží |
| --- | --- | --- |
| `full` | Všechny endpointy API. Je to výchozí hodnota. | Interní nástroje, skripty a integrace, které spravují domény, kontakty, šablony nebo webhooky. |
| `sending` | Jen endpointy pro odesílání uvedené níže. | Aplikační servery, které jen odesílají e-maily. |

Klíč s oprávněním `sending` může volat tyto endpointy a nic jiného:

| Endpoint | Popis |
| --- | --- |
| `POST /emails` | [Odeslání e-mailu](/cs/docs/api-reference/emails/send/) |
| `POST /emails/{id}` | [Úprava naplánovaného e-mailu](/cs/docs/api-reference/emails/update/) |
| `POST /emails/{id}/cancel` | [Zrušení e-mailu](/cs/docs/api-reference/emails/cancel/) |
| `POST /emails/{id}/retry` | [Opakované odeslání e-mailu](/cs/docs/api-reference/emails/retry/) |
| `POST /emails/{id}/forward` | [Přeposlání e-mailu](/cs/docs/api-reference/emails/forward/) |

Čtení e-mailů (výpis, načtení, surový MIME, tělo, metadata, přílohy a stav) vyžaduje klíč s oprávněním `full`. Když klíč s oprávněním `sending` zavolá jakýkoli jiný endpoint, API vrátí `403` se zprávou `Permission denied: full` (u endpointů pro čtení e-mailů `Permission denied: read`).

Oprávnění každého endpointu uvádí stránka [Všechny endpointy](/cs/docs/api-reference/endpoints/).

## Omezte klíč na jednu doménu

Klíč s oprávněním `sending` lze také uzamknout na jednu odesílací doménu. Při [vytvoření klíče](/cs/docs/api-reference/api-keys/create/) předejte ID domény v poli `sending_domain_id`. Omezený klíč může odesílat jen z adres na této doméně. Jakákoli jiná doména v poli `from` vrátí `403`:

```json
{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}
```

Omezení na doménu platí jen pro klíče s oprávněním `sending`. Klíč s oprávněním `full` má vždy přístup ke všem doménám ve workspace.

## Přístupové tokeny OAuth

Aplikace, které jednají jménem uživatele Emailitu, například MCP klienti a integrace třetích stran, o API klíč nežádají. Místo toho používají OAuth 2.1: uživatel se přihlásí do Emailitu, vybere workspace, které aplikace smí používat (všechny, nebo jen vybrané), a schválí oprávnění `sending`, nebo `full`. Aplikace pak dostane přístupový token. Uživatel může tento přístup změnit nebo odvolat na stránce [Připojené aplikace](/cs/docs/account/connected-apps/).

Přístupové tokeny posílejte ve stejné hlavičce jako API klíče:

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
```

Přístupový token platí 15 minut a pracuje s výchozím workspace uděleného přístupu, s uděleným oprávněním a s rolí uživatele v tomto workspace. Aplikace ho obnovují obnovovacím tokenem. Jak takovou aplikaci vytvořit, popisuje stránka [OAuth aplikace](/cs/docs/developers/oauth-apps/).

## Chyby autentizace

Autentizace proběhne před vším ostatním, takže tyto chyby může vrátit kterýkoli endpoint.

| Stav | `message`, nebo `error` | Příčina | Řešení |
| --- | --- | --- | --- |
| `401` | `API key required` | Hlavička `Authorization` chybí, nebo nezačíná na `Bearer `. | Pošlete `Authorization: Bearer <key>`. |
| `401` | `Valid API key required` | Hlavička má předponu `Bearer`, ale žádný token. | Zkontrolujte, že proměnná s vaším klíčem není prázdná. |
| `401` | `Invalid API key` | Klíč neexistuje, byl smazán nebo znovu vygenerován (starý tajný údaj přestane fungovat), nebo vypršel token OAuth. | Použijte aktuální klíč, nebo obnovte token OAuth. |
| `403` | `Workspace is suspended` | Workspace je zablokovaný. | [Napište podpoře](/contact/). |
| `403` | `Permission denied: full` | Klíč s oprávněním `sending` zavolal endpoint, který vyžaduje `full`. | Použijte klíč s oprávněním `full`. |
| `403` | `Domain not authorized` | Klíč omezený na doménu odesílal z jiné domény. | Odesílejte z domény klíče, nebo použijte jiný klíč. |
| `403` | `unverified_workspace_recipient` | Workspace ještě není ověřený a některý příjemce není členem workspace. | Viz [Neověřené workspace](#unverified-workspaces). |
| `503` | `Authentication service unavailable` | Dočasný problém na naší straně. | Zopakujte požadavek s rostoucím odstupem. |

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**403 Oprávnění**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}
```

**403 Zablokováno**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}
```

**403 Neověřeno**

```json
{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}
```

## Neověřené workspace

Nové workspace začínají jako neověřené. Dokud Emailit neschválí [produkční přístup](/cs/docs/workspaces/production-access/), API odesílá jen na e-mailové adresy účtů členů workspace. Odeslání, opakované odeslání nebo přeposlání komukoli jinému vrátí `403` s kódem `unverified_workspace_recipient` a seznamem `blocked_recipients` a kampaně nelze odeslat vůbec. Na všechno ostatní vaše API klíče fungují normálně.

## Uchovejte klíče v tajnosti

API klíč dává přístup k vašemu workspace, takže s ním zacházejte jako s heslem.

- Volejte API jen ze svého serveru. Nikdy nedávejte klíč do JavaScriptu v prohlížeči, do mobilní aplikace ani do jiného kódu, který běží na cizím zařízení.
- Neukládejte klíče do správy verzí. Načítejte je z proměnných prostředí nebo ze správce tajných údajů.
- Pro každou aplikaci a prostředí vytvořte samostatný klíč a pojmenujte ho podle místa použití, abyste mohli jeden odvolat a ostatní nerozbít.
- Dejte každému klíči jen takový přístup, jaký potřebuje: pro většinu aplikací stačí klíč s oprávněním `sending` omezený na jednu doménu.
- Kontrolujte pole `last_used_at` ve [výpisu API klíčů](/cs/docs/api-reference/api-keys/list/) a mažte klíče, které už nepoužíváte.
- Pokud klíč unikne, hned ho [vygenerujte znovu](/cs/docs/api-reference/api-keys/regenerate/), nebo [smažte](/cs/docs/api-reference/api-keys/delete/). Starý tajný údaj okamžitě přestane fungovat.

## Související

  - [API klíče](/cs/docs/developers/api-keys/): Vytvářejte, omezujte a vyměňujte klíče ve webovém rozhraní.
  - [Chyby](/cs/docs/api-reference/errors/): Všechny formáty chyb a stavové kódy.
  - [OAuth aplikace](/cs/docs/developers/oauth-apps/): Umožněte uživatelům připojit vaši aplikaci k jejich workspace.
  - [Produkční přístup](/cs/docs/workspaces/production-access/): Nechte si ověřit workspace, abyste mohli odesílat komukoli.

---
Zdroj: https://emailit.com/cs/docs/api-reference/authentication/