# Přihlášení a API klíče · Dokumentace DameDokladu

> Jak se ověřuje veřejné API a MCP, jak založit API klíč a co dovolují jeho rozsahy.

Source: https://damedoklad.cz/docs/authentication/

# Přihlášení a API klíče

Jak se ověřuje veřejné API a MCP, jak založit API klíč a co dovolují jeho rozsahy.

Veřejné API na `https://api.damedoklad.cz/v1` se ověřuje **API klíčem** nebo **přístupovým tokenem OAuth**. MCP server na `https://api.damedoklad.cz/mcp` přijímá obojí, o OAuth píšeme v části [MCP server](/docs/mcp/).

## API klíč

Klíč pošlete v hlavičce `Authorization`:

```bash
curl https://api.damedoklad.cz/v1/series \
  -H "Authorization: Bearer secret_…"
```

-   Klíč začíná `secret_` a patří **jedné firmě**. Na `/v1` neposíláte hlavičku `X-Tenant`: firma vyplývá z klíče.
-   Celý klíč uvidíte jen jednou, při založení. Ukládáme jen jeho otisk SHA-256, takže ho už nejde znovu zobrazit.
-   Zacházejte s ním jako s heslem: nepatří do kódu v prohlížeči ani do repozitáře.

## Rozsahy

Klíč má jeden ze dvou rozsahů a k tomu může mít zvláštní oprávnění odesílat:

| Rozsah | Co dovoluje |
| --- | --- |
| `read` | Jen požadavky `GET`. Na cokoli jiného dostanete `403` s kódem `insufficient_scope`. Výjimkou je výměna `POST /v1/pohoda/xml`, kde se výpis posílá metodou POST: čtení projde a každý zápis se odmítne. |
| `full` | Čtení i zápis, s právy vlastníka firmy v rámci `/v1`. |
| `send` | Navíc k `full`: potvrdit odeslání příkazu k úhradě do banky a podání úřadu. **Plný přístup ho neobsahuje.** Viz níže. |

Každému napojení dejte nejužší rozsah, se kterým si vystačí. Připojení přes OAuth má stejné rozsahy, vyberete je při schválení; zápis pak omezuje i vaše vlastní role ve firmě. Klíč i připojení člověka s [vlastní rolí](/docs/guides/team/) smí jen to, co jeho role, a to i klíč `read`.

## Odesílání přes API a MCP

Klíč s plným přístupem příkaz k úhradě a podání připraví, ale neodešle. Dostane `403` s kódem `send_scope_required`. Odeslat smí jen když platí všechno z tohoto seznamu:

-   Vlastník firmy to zapnul v **Nastavení > Další > API a MCP** a nastavil limity. Ve výchozím stavu je to vypnuté.
-   Klíč nebo připojení má oprávnění odesílat. Klíč s ním založí jen vlastník přímo v aplikaci. Připojení přes OAuth o `send` musí samo požádat a na stránce souhlasu to uvidíte.
-   Člověk, kterému klíč patří, je ve firmě dnes vlastník.
-   Částka se vejde do limitu na jeden příkaz i do denního limitu, podání do denního počtu.

Požadavek musí uvést otisk přesných dat, který vrátila příprava. Provozovatel musí mít odesílání povolené stejně jako v aplikaci a banka dál chce svůj vlastní podpis. Každé odeslání se zapíše do auditu s názvem klíče a vlastník dostane upozornění a e-mail.

Limity jsou v korunách, takže příkaz v jiné měně přes API neodejde. Klíč může odesílání jen vypnout nebo limit snížit, zapnout ho a limit zvýšit lze jen v aplikaci.

## Založení klíče

Klíč založíte v aplikaci v **Nastavení > API a MCP** nebo přes API. Může to vlastník nebo účetní a tarif firmy musí zahrnovat API; jinak dostanete `402` s kódem `plan_limit`.

```bash
curl https://api.damedoklad.cz/v1/api-keys \
  -H "Authorization: Bearer $DAMEDOKLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Napojení e-shopu", "scope": "read" }'
```

```json
{
  "object": "api_key",
  "id": "key_…",
  "name": "Napojení e-shopu",
  "scope": "read",
  "hint": "secret_abcdefg…",
  "secret": "secret_abcdefg…celý klíč"
}
```

Klíč odvoláte na stejném místě nebo přes `DELETE /v1/api-keys/{id}`. Všechno, co ho používá, okamžitě přestane fungovat.

## API aplikace

Samotná aplikace používá `/app/v1` s krátkodobým přístupovým tokenem (15 minut), obnovovacím tokenem v cookie a hlavičkou `X-Tenant` s ID firmy. Nabízí stejné operace jako `/v1`, s právy podle role přihlášeného uživatele, a pár dalších jen pro aplikaci. Pro napojení používejte `/v1` a API klíč.

## Chyby přihlášení

| Stav | Význam |
| --- | --- |
| `401` | Klíč chybí nebo je neplatný. Zpráva je `API key required` nebo `Invalid API key`. |
| `403` | Klíč nebo připojení je jen pro čtení, kód `insufficient_scope`. |

Ostatní chyby najdete na stránce [Chyby a limity](/docs/errors-and-limits/).