Autentizace a API klíče

Každé volání nese API klíč vydaný Redque v hlavičce X-Api-Key. Existují dva druhy klíčů a každé API přijímá právě jeden z nich.

	Partnerský klíč	Klíč koncového uživatele
Prefix	`rqp_`	`rqe_`
Ověřuje	Vás, partnera	Jednoho z vašich koncových uživatelů
Přijímá ho	Partner API	Document API
Umožňuje	Spravovat koncové uživatele, jejich účastníky a klíče a vaše webhooky	Odesílat, zjišťovat stav, číst schránku a vyhledávat příjemce — jen za vlastní účastníky daného koncového uživatele
Vydává	Redque, nebo vy sami samoobslužnou rotací	Vy, přes Partner API

GET /v1/end-users HTTP/1.1
Host: partnerapi.peppol.redque.com
X-Api-Key: rqp_prod_3f9c0a7d51e2b846_Xq3v…

Klíč poslaný do nesprávného API je odmítnut s 401 a odpověď uvede, kde klíč funguje, například: „This is a partner API key. It authenticates the Partner API, not the document exchange API; send a document with an End User key."

Formát klíče

{druh}{prostředí}_{keyId}_{secret}, například rqe_prod_3f9c0a7d51e2b846_Xq3v…:

druh: rqp_ nebo rqe_;
prostředí: sandbox nebo prod. Každé prostředí přijímá jen své vlastní klíče;
keyId: 16 hexadecimálních znaků identifikujících klíč. Není tajné a objevuje se ve výpisech klíčů a v auditních záznamech;
secret: 43 znaků, 256 bitů.

Druh a prostředí jsou viditelné, aby klíč na první pohled poznali vy, vaše podpora. S celým klíčem ale zacházejte jako s secretem.

Vlastnost	Hodnota
Platnost	365 dní od vydání. Každá ověřená odpověď nese hlavičku `X-Api-Key-Expires`
Uložení	Redque uchovává jen otisk (hash). Ztracený klíč nelze obnovit, jen nahradit.
Poslední použití	Zaznamenává se u každého klíče, nejvýše jednou za 5 minut.
Chybný, prošlý, zrušený nebo nesprávný druh klíče	`401`, důvod je v poli `detail`
Pozastavený partner	`403`, pro jeho vlastní klíče i klíče jeho koncových uživatelů

Dva sloty pro rotaci bez výpadku

Vy i každý váš koncový uživatel máte dva sloty na klíče, 1 a 2. Každý obsahuje nejvýše jeden klíč a oba fungují současně. Vydání klíče do slotu nahradí klíč, který v něm byl, a ten okamžitě přestane fungovat; druhého slotu se to nikdy nedotkne. Postup rotace:

Vydejte nový klíč do slotu, který nepoužíváte.
Nasaďte ho všude, kde se používá starý klíč.
Starý slot zrušte, nebo ho nechte do příští rotace.

Výpis klíčů ukazuje u každého slotu lastUsedAt, podle kterého poznáte, který slot se skutečně používá, a tedy který je bezpečné nahradit.

Partnerské klíče

První partnerský klíč do slotu 1 vám Redque vydá při založení partnerského účtu, spolu s kontaktním e-mailem, který k vám eviduje. Pro získání přístupu do sandbox prostředí nás kontaktujte na adrese info@redque.cz. Své klíče vypíšete takto:

curl -s "$PARTNER_API/v1/api-keys" -H "X-Api-Key: $PARTNER_KEY"

currentSlot v odpovědi je slot klíče, kterým bylo volání provedeno.

Samoobslužná rotace a obnovení

Rotace partnerského klíče nevyžaduje API klíč, takže stejný postup poslouží i po ztrátě, úniku nebo vypršení klíče. Důkazem je jednorázový kód zaslaný na váš evidovaný kontaktní e-mail.

# 1. Vyžádejte si kód pro slot, který chcete (znovu) vydat. Odpověď je vždy 202.
curl -s -X POST "$PARTNER_API/v1/api-key-rotations" -H "Content-Type: application/json" \
  -d '{ "partnerId": "…", "slot": 2 }'

# 2. Potvrďte kódem z e-mailu. Nový klíč je pouze v této odpovědi.
curl -s -X POST "$PARTNER_API/v1/api-key-rotations/confirm" -H "Content-Type: application/json" \
  -d '{ "partnerId": "…", "slot": 2, "code": "4821-0937" }'

{ "slot": 2, "keyId": "…", "apiKey": "rqp_prod_…", "expiresAt": "…" }

Žádost vždy vrátí 202, ať byl kód odeslán, nebo ne. Kódy se posílají jen aktivním partnerům s kontaktním e-mailem, nejvýše 3 za hodinu.
Kód má 8 číslic, platí 15 minut, lze ho použít jednou a je vázán na partnera a slot. Po 5 chybných pokusech se zablokuje. Nová žádost pro stejný slot zneplatní předchozí kód.
Klíč, který ve slotu je, funguje až do potvrzení kódu, takže kód vyžádaný někým jiným je neškodný, dokud ho někdo také nepotvrdí.
Po rotaci přijde na kontaktní adresu upozornění. Pokud jste rotaci neprováděli, ihned kontaktujte Redque.
Oba endpointy povolují 10 volání za minutu z jedné IP adresy, pak vracejí 429.

Klíče koncových uživatelů

Klíč koncového uživatele slouží k přístupu vašeho softwaru k Document API pod identitou koncového uživatele. Vydáváte ho svým partnerským klíčem a vrátí se jen jednou:

# Vydání (nebo nahrazení) klíče ve slotu 1
curl -s -X POST "$PARTNER_API/v1/end-users/$END_USER_ID/api-keys/1/rotate" -H "X-Api-Key: $PARTNER_KEY"

# Metadata obou slotů — nikdy samotné klíče
curl -s "$PARTNER_API/v1/end-users/$END_USER_ID/api-keys" -H "X-Api-Key: $PARTNER_KEY"

# Zrušení slotu 1
curl -s -X DELETE "$PARTNER_API/v1/end-users/$END_USER_ID/api-keys/1" -H "X-Api-Key: $PARTNER_KEY"

Koncoví uživatelé nemají samoobslužnou rotaci a Redque koncové uživatele nikdy nekontaktuje: vydávání, rotace a předávání klíčů vašim koncovým uživatelům zabezpečujete Vy jako partner.
Odpojení koncového uživatele: zrušte oba sloty. Jeho účastníci zůstanou registrovaní a dokumenty jim dál chodí do schránky, ale nikdo je nepřečte ani neodešle nic nového, dokud nevydáte nový klíč.
Pokud váš software běží centrálně, a ne u koncového uživatele, drží klíče všech koncových uživatelů; ukládejte je jako secrets, každý zvlášť.