# API klíče

> Vytvářejte API klíče s plným přístupem a jen pro odesílání, omezte je na doménu, používejte je pro SMTP a vyměňujte je bez výpadku.

API klíče autentizují vaše požadavky na REST API, připojení přes SMTP a relace na MCP serveru přihlášené API klíčem. Tato stránka vysvětluje dva rozsahy oprávnění klíčů, jak klíče vytvářet a spravovat a jak je bezpečně ukládat a vyměňovat.

## Jak API klíče fungují

- Každý klíč patří do jednoho workspace. Vše, co s ním uděláte, se odehraje v tomto workspace.
- Nové klíče začínají na `secret_` a za ním následuje 32 písmen a číslic, například `secret_••••••••`. Klíče vytvořené před zavedením této předpony fungují dál.
- Emailit zobrazí celý klíč jen jednou, když ho vytvoříte nebo znovu vygenerujete. Hned si ho zkopírujte; znovu ho zobrazit nejde.
- Klíč posíláte jako bearer token: `Authorization: Bearer secret_…`. U SMTP je klíč heslem.

## Rozsahy oprávnění

Každý klíč má jeden ze dvou rozsahů oprávnění. Rozsah zvolíte při vytváření klíče.

| | Full Access (`full`) | Sending Only (`sending`) |
| --- | --- | --- |
| Odeslání e-mailu (`POST /emails`) | Ano | Ano |
| Přeplánování, zrušení, opakované odeslání a přeposlání e-mailu | Ano | Ano |
| SMTP relay | Ano | Ano |
| Čtení e-mailů (výpis, načtení, surový MIME, tělo, metadata, přílohy) | Ano | Ne |
| Domény, šablony, kontakty, seznamy kontaktů, blokované adresy, webhooky, události, kampaně, automatizace, ověřování a API klíče | Ano | Ne |
| Nástroje MCP | Všechny nástroje | `send-email`, `update-email`, `cancel-email`, `retry-email`, `forward-email` a `get-current-workspace` |
| Lze omezit na jednu odesílací doménu | Ne | Ano |

Klíč jen pro odesílání, který zavolá jakýkoli jiný endpoint, dostane `403` se zprávou jako `Permission denied: read`. Klíče s plným přístupem používejte pro interní úlohy, které spravují zdroje, a klíče jen pro odesílání pro vše, co potřebuje jen odesílat.

### Omezte klíč na jednu doménu

Při vytváření klíče jen pro odesílání můžete vybrat jednu ověřenou odesílací doménu. Klíč pak může odesílat jen z adres na této doméně:

- Přes API vrátí odeslání z jiné domény `403` s `"error": "Domain not authorized"`.
- Přes SMTP se zpráva po `DATA` odmítne s `530 API key is restricted to sending domain: …`.

Omezené klíče se hodí jako přístupové údaje pro jednotlivé aplikace nebo zákazníky a pro klíče, které musíte předat softwaru třetích stran, například pluginu CMS.

## Než začnete

- K vytváření, úpravám, novému vygenerování a mazání klíčů potřebujete ve workspace roli **Admin**. Členové s rolí **Member** seznam klíčů vidí, ale nemohou ho měnit. Viz [Členové a role](/cs/docs/workspaces/members-and-roles/).
- K odesílání s klíčem potřebujete alespoň jednu [ověřenou odesílací doménu](/cs/docs/domains/add-a-domain/).

## Vytvořte API klíč

**Webové rozhraní**

  1. **Otevřete API klíče.** Otevřete **Email API → API Keys** a vyberte **Add API key**.

  2. **Pojmenujte klíč.** Do pole **Name** zadejte název, ze kterého je poznat, kde se klíč používá, například `production-web` nebo `wordpress-blog`. Názvy musí být ve workspace jedinečné.

  3. **Zvolte rozsah oprávnění.** V poli **Scope** zvolte **Full Access**, nebo **Sending Only**.

  4. **Volitelně omezte doménu.** U klíče jen pro odesílání vyberte v poli **Domain** odesílací doménu, nebo pole nechte prázdné a povolte všechny ověřené domény.

  5. **Vytvořte a zkopírujte klíč.** Vyberte **Create**. Zkopírujte klíč z dialogového okna a uložte ho do správce tajných údajů dřív, než okno zavřete. Emailit klíč zobrazí jen jednou.

**API**

  Zavolejte [Vytvoření API klíče](/cs/docs/api-reference/api-keys/create/) s klíčem s plným přístupem. Výchozí hodnota `scope` je `full`; `sending_domain_id` platí jen pro klíče jen pro odesílání.

```bash
curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'
```

  Pole `key` obsahuje jen odpověď `201`:

```json
{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}
```

  Pokud je název už obsazený, vrací `409`.

## Použijte klíč

Klíč předávejte v hlavičce `Authorization` každého požadavku na API:

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'
```

Při odesílání přes SMTP použijte klíč jako heslo:

| Nastavení | Hodnota |
| --- | --- |
| Server | `smtp.emailit.com` |
| Port | `587` (STARTTLS, doporučeno), `465` (TLS), `2525` nebo `2587` (STARTTLS) |
| Uživatelské jméno | `emailit` |
| Heslo | Váš API klíč |

Všechny možnosti najdete na stránce [Nastavení SMTP](/cs/docs/smtp/settings/).

## Spravujte klíče

Když klíč otevřete v **Email API → API Keys**, uvidíte jeho rozsah oprávnění, doménu, datum **Created**, čas **Last used** a nastavení SMTP, které s ním máte použít.

| Akce | Co se stane | API |
| --- | --- | --- |
| **Edit** | Přejmenuje klíč. Uloží se jen název; pokud chcete změnit rozsah oprávnění nebo omezení na doménu, vytvořte nový klíč a přejděte na něj. | [Úprava API klíče](/cs/docs/api-reference/api-keys/update/) |
| **Regenerate** | Vydá pro stejný klíč nový tajný údaj a jednou ho zobrazí. Starý tajný údaj okamžitě přestane fungovat. Klíč si ponechá ID, název, rozsah oprávnění i doménu a údaj **Last used** se vynuluje. | [Nové vygenerování API klíče](/cs/docs/api-reference/api-keys/regenerate/) |
| **Delete** | Klíč okamžitě přestane fungovat a zmizí ze seznamu. Tuto akci nelze vrátit zpět. | [Smazání API klíče](/cs/docs/api-reference/api-keys/delete/) |

Údaj **Last used** se aktualizuje pokaždé, když klíč autentizuje požadavek na API nebo přihlášení přes SMTP. U klíče, který ještě nikdy nebyl použit, se zobrazí **Never**. Endpointy API, které přijímají ID klíče, přijímají i jeho název.

## Ukládejte klíče bezpečně

- **Uchovávejte klíče na serveru.** Nikdy nevkládejte klíč do JavaScriptu v prohlížeči, mobilní aplikace, veřejného repozitáře ani tiketu pro podporu. Kdokoli s klíčem může odesílat e-maily vaším jménem a utrácet vaše kredity.
- **Používejte proměnné prostředí nebo správce tajných údajů.** Klíč načítejte za běhu, například z `EMAILIT_API_KEY`. Soubory `.env` přidejte do `.gitignore`.
- **Dejte každé aplikaci a prostředí vlastní klíč.** Díky samostatným klíčům pro produkci, staging a každý nástroj třetí strany snadno zjistíte, kdo co odeslal, a jeden klíč odvoláte, aniž byste museli sahat na ostatní.
- **Používejte co nejužší oprávnění.** Pokud aplikace jen odesílá e-maily, dejte jí klíč jen pro odesílání, a kde to jde, omezený na její doménu.
- **Sledujte využití.** Stránka **Email API → Logs** uvádí požadavky přes API a SMTP pro jednotlivé klíče a e-maily v **Email API → Emails** můžete filtrovat podle API klíče. Viz [Logy požadavků](/cs/docs/logs/request-logs/).
- **Při úniku jednejte rychle.** Pokud klíč unikne, okamžitě ho znovu vygenerujte nebo smažte a pak v logech zkontrolujte nečekaná odeslání.

## Vyměňte klíč bez výpadku

Nové vygenerování klíče starý tajný údaj okamžitě odstřihne, proto ho používejte jen tehdy, když je klíč kompromitovaný. Při plánované výměně nechte starý a nový klíč nějakou dobu fungovat souběžně:

1. **Vytvořte nový klíč.** Přidejte klíč se stejným rozsahem oprávnění a omezením na doménu, jaké má klíč, který nahrazujete. Dejte mu název s datem, například `production-web-2026-10`.

2. **Nasaďte nový klíč.** Aktualizujte tajný údaj ve správci tajných údajů nebo v prostředí a nasaďte ho na všechny servery, workery a plánované úlohy, které používají starý klíč.

3. **Ověřte přechod.** Otevřete nový klíč a zkontrolujte, že je údaj **Last used** čerstvý. V **Email API → Logs** vyfiltrujte starý klíč a zkontrolujte, že požadavky ustaly.

4. **Smažte starý klíč.** Až se čas **Last used** u starého klíče přestane měnit, klíč smažte.

## Řešení problémů

| Příznak | Příčina | Řešení |
| --- | --- | --- |
| `401` `Invalid API key` | Klíč byl smazán, znovu vygenerován nebo špatně opsán. | Zkopírujte do konfigurace aktuální klíč včetně předpony `secret_`. |
| `403` `Permission denied: read` nebo `Permission denied: full` | Klíč jen pro odesílání zavolal endpoint mimo svůj rozsah oprávnění. | Pro toto volání použijte klíč s plným přístupem. |
| `403` `Domain not authorized` | Klíč je omezený na jinou doménu, než je doména adresy `from`. | Odesílejte z domény klíče, nebo použijte jiný klíč. |
| SMTP `535 Authentication failed` | Heslo není platný API klíč. | Jako heslo použijte API klíč a jako uživatelské jméno `emailit`. |

## Související

  - [Autentizace](/cs/docs/api-reference/authentication/): Jak se požadavky autentizují.
  - [API klíče – API](/cs/docs/api-reference/api-keys/): Vytváření, výpis, úpravy, nové vygenerování a mazání klíčů.
  - [Nastavení SMTP](/cs/docs/smtp/settings/): Server, porty, TLS a přístupové údaje.
  - [Zabezpečení](/cs/docs/security/): Jak Emailit chrání váš účet a data.

---
Zdroj: https://emailit.com/cs/docs/developers/api-keys/