Nyilvános API

OAuth-alkalmazások

Ha nem a saját fiókodat kezeled, hanem másokét: authorization code folyamat kötelező PKCE-vel és lejáró tokenekkel.

Potřebujete OAuth?

Co vytváříteCo použít
Vlastní skript nebo automatizace pro váš pracovní prostor.API klíč. Viz stránku Autentizace.
AI agent pro váš kalendář.MCP klíč. Viz sekci MCP.
Aplikace, kterou ostatní používají se svým účtem Posty.OAuth. Tato stránka.
Většina čtenářů to nepotřebuje

Pokud píšete kód pro vlastní účet, je API klíč jednodušší a umí totéž. OAuth potřebujete, když vaši uživatelé udělují vaší aplikaci přístup ke svým účtům Posty.

Postup

  1. 1
    Zaregistrujte aplikaci
    Aplikaci může povolit člen pracovního prostoru s rolí Superadmin. Při registraci zadáte adresy přesměrování.
  2. 2
    Pošlete uživatele na autorizační stránku
    Tok autorizačního kódu s povinným PKCE. Na této stránce uživatel uvidí, o jaká oprávnění žádáte.
  3. 3
    Vyměňte kód za token
    Odešlete vrácený kód a ověřovací řetězec PKCE. Získáte přístupový token.
  4. 4
    Zavolejte API s tokenem
    Token odešlete v hlavičce Authorization s předponou Bearer.
curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: Bearer pos_a_tokened"

Co je povinné

  • PKCE s výzvou S256 u každého požadavku. Zaregistrovat lze i klienta bez tajného klíče, ale ne bez PKCE.
  • Hodnota redirect_uri se musí přesně shodovat s některou z registrovaných adres. Shoda podle předpony ani zástupné znaky se nepovolují.
  • Tokenům končí platnost a obnovovací tokeny rotujeme. Ukládáme pouze jejich hashovanou podobu.
  • Aplikaci povoluje Superadmin pracovního prostoru.

Tokeny

Token platí pro rozsahy oprávnění, se kterými uživatel souhlasil. Při každém volání se oprávnění z tokenu omezí podle aktuální role uživatele. Snížení role se projeví při dalším volání. Nemusíte čekat, až token vyprší.

Seznam rozsahů oprávnění je stejný jako u API klíčů. Viz stránku Autentizace. Token vydaný pro zdroj MCP nelze použít pro REST API a naopak: oba zdroje mají samostatný identifikátor a kontrolujeme deklarovanou hodnotu audience.

Metadata

Klient může všechny adresy pro tento postup načíst ze strojově čitelných metadat, takže je nemusí mít napevno v kódu:

DokumentAdresa
Authorization server metadatahttps://api.posty.hu/.well-known/oauth-authorization-server
Protected resource metadatahttps://api.posty.hu/.well-known/oauth-protected-resource
Metadata zdroje MCPhttps://api.posty.hu/.well-known/oauth-protected-resource/mcp-oauth

Uvádí je také odpověď /public/v1/status, a to bez autentizace.

Zrušení přístupu

Uživatel může v Posty na stránce Nastavení → Povolené aplikace kdykoli zrušit přístup vaší aplikaci. Zrušení platí okamžitě: další volání s tokenem vrátí stav 401.

Tento případ ošetřete: stav 401 zde není chyba, ale rozhodnutí uživatele. Požádejte znovu o autorizaci. Požadavek se stejným tokenem neopakujte.

Něco vám na této stránce chybí? Napište na [email protected] nebo na stránce Nápověda vyplňte formulář.