Vytvoření OAuth aplikace

Emailit provozuje autorizační server OAuth 2.1 na https://api.emailit.com. Použijte ho, když vytváříte integraci, například CRM, no-code nástroj nebo AI klienta, která jedná jménem uživatelů Emailitu. Uživatelé se přihlásí a schválí přístup v prohlížeči a vy dostanete tokeny pro workspace, které vyberou, aniž byste kdy pracovali s jejich API klíči. Stejný postup používá MCP server.

Jak to funguje

1. Zaregistrujte klienta dynamickou registrací klienta, nebo hostujte dokument s metadaty klienta.

2. Pošlete uživatele na autorizační URL s výzvou PKCE (code challenge).

3. Uživatel se přihlásí do Emailitu, vybere workspace, které může vaše aplikace používat, a schválí požadovaný rozsah oprávnění.

4. Emailit přesměruje zpět na vaše URI pro přesměrování s jednorázovým autorizačním kódem.

5. Vyměňte kód za přístupový token platný 15 minut a obnovovací token.

6. Volejte API s přístupovým tokenem a po vypršení ho obnovte.

Endpointy

Všechny cesty jsou na https://api.emailit.com.

Zjistěte metadata serveru

curl https://api.emailit.com/.well-known/oauth-authorization-server

{
  "issuer": "https://api.emailit.com",
  "authorization_endpoint": "https://api.emailit.com/oauth/authorize",
  "token_endpoint": "https://api.emailit.com/oauth/token",
  "registration_endpoint": "https://api.emailit.com/oauth/register",
  "revocation_endpoint": "https://api.emailit.com/oauth/revoke",
  "jwks_uri": "https://api.emailit.com/.well-known/jwks.json",
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "response_types_supported": ["code"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "client_id_metadata_document_supported": true,
  "authorization_response_iss_parameter_supported": true,
  "scopes_supported": ["sending", "full"]
}

MCP klienti místo toho začínají u metadat chráněného zdroje. Neautentizovaný požadavek na https://api.emailit.com/mcp vrací 401 s WWW-Authenticate: Bearer resource_metadata="https://api.emailit.com/.well-known/oauth-protected-resource/mcp" a tento dokument odkazuje na autorizační server:

{
  "resource": "https://api.emailit.com/mcp",
  "authorization_servers": ["https://api.emailit.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["sending", "full"]
}

Rozsahy oprávnění

full už zahrnuje vše, co povoluje sending. Pokud vaše aplikace jen odesílá, žádejte o sending, jinak o full; přijímá se i sending full oddělené mezerou. Pokud scope vynecháte, Emailit použije všechna oprávnění, která klient zaregistroval.

Zaregistrujte klienta

Klienta můžete zaregistrovat dvěma způsoby. Oba fungují se všemi postupy na této stránce.

Dynamická registrace klienta

Pošlete požadavek na registraci. Autentizace není potřeba a z každé IP adresy lze zaregistrovat až 20 klientů za hodinu.

curl https://api.emailit.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme CRM",
    "redirect_uris": ["https://crm.acme.com/oauth/emailit/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "full",
    "token_endpoint_auth_method": "client_secret_basic",
    "client_uri": "https://crm.acme.com",
    "logo_uri": "https://crm.acme.com/logo.png"
  }'

Odpověď 201 zopakuje metadata a přidá client_id. Důvěrní klienti dostanou také client_secret, který se zobrazí jen jednou:

{
  "client_id": "3e8a1f52-7c4b-4d29-8e6f-1a5b9c0d2e73",
  "client_id_issued_at": 1790847000,
  "client_name": "Acme CRM",
  "redirect_uris": ["https://crm.acme.com/oauth/emailit/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "full",
  "token_endpoint_auth_method": "client_secret_basic",
  "client_uri": "https://crm.acme.com",
  "logo_uri": "https://crm.acme.com/logo.png",
  "client_secret": "Ky7WI2z5HxoT6q1z19tuiIev_U1zX0_FKhIIfh0OBco",
  "client_secret_expires_at": 0
}

client_secret_expires_at je vždy 0: tajné klíče klientů nevyprší. Každý klient, veřejný i důvěrný, musí používat PKCE.

Dokument s metadaty klienta

Pokud vaše aplikace může hostovat statický soubor JSON, registraci můžete vynechat. Publikujte dokument na HTTPS URL a tuto URL použijte jako client_id:

{
  "client_id": "https://crm.acme.com/oauth/client.json",
  "client_name": "Acme CRM",
  "client_uri": "https://crm.acme.com",
  "logo_uri": "https://crm.acme.com/logo.png",
  "redirect_uris": ["https://crm.acme.com/oauth/emailit/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none",
  "scope": "full"
}

• client_id v dokumentu se musí přesně shodovat s URL dokumentu.
• token_endpoint_auth_method musí být none. Jde o veřejné klienty, kteří se spoléhají na PKCE.
• URI pro přesměrování s HTTPS musí mít stejný název hostitele jako dokument.
• Emailit dokument stáhne během autorizace s časovým limitem 5 sekund a bez následování přesměrování a na 5 minut si ho uloží do mezipaměti.
• Stránka se souhlasem místo client_name zobrazuje název hostitele dokumentu, například crm.acme.com.

Tuto metodu používají AI klienti: ChatGPT, Claude a Grok se identifikují vlastními dokumenty s metadaty klienta, takže se připojí bez předchozí registrace. U Groku Emailit přijímá také přesměrování na console.x.ai.

Pravidla pro URI pro přesměrování

• URI https:// jsou povolená.
• http:// je povolené jen pro loopback: 127.0.0.1, localhost a [::1]. U loopback URI se port při autorizaci může lišit, ale hostitel, cesta a dotaz se musí shodovat. localhost a 127.0.0.1 jsou různí hostitelé.
• Pro nativní aplikace jsou povolená vlastní schémata, například cursor://, vscode:// nebo com.acme.crm://.
• URI se schématy file, ftp, data, javascript, blob, about a vbscript a jakékoli URI s #fragment se odmítnou.
• Kromě portů u loopbacku se redirect_uri, které pošlete, musí přesně shodovat s některým zaregistrovaným.

Pošlete uživatele do Emailitu

Pro každou autorizaci vygenerujte ověřovací kód (code verifier) a výzvu PKCE a náhodnou hodnotu state:

import { createHash, randomBytes } from 'node:crypto';

const codeVerifier = randomBytes(32).toString('base64url');
const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
const state = randomBytes(16).toString('base64url');
// Store codeVerifier and state in the user's session.

Pak přesměrujte prohlížeč uživatele na autorizační endpoint:

https://api.emailit.com/oauth/authorize
  ?response_type=code
  &client_id=3e8a1f52-7c4b-4d29-8e6f-1a5b9c0d2e73
  &redirect_uri=https%3A%2F%2Fcrm.acme.com%2Foauth%2Femailit%2Fcallback
  &scope=full
  &state=Jq3k9V0n2xR7bLm1
  &code_challenge=zsrvXVr2pbLDHbccAx_NY9osQ6nwqTnDZlIeFWKQOsg
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.emailit.com

Tuto URL otevřete v prohlížeči uživatele. Nestahujte ji ze svého backendu.

Co uživatel uvidí

1. Přihlášení do Emailitu. Uživatel zadá e-mail a heslo. Pokud pro dvoufázové ověření používá ověřovací aplikaci, zadá potom kód z ní nebo záložní kód.
2. Výběr workspace. Stránka zobrazí vaše logo, název klienta (nebo název hostitele vašeho dokumentu s metadaty) a oprávnění, o která žádáte. Uživatel vybere All my workspaces, což zahrnuje i workspace, které vytvoří nebo ke kterým se připojí později, nebo Only these workspaces se zaškrtnutými workspace, a zvolí, ve kterém vaše aplikace začne.
3. Povolení přístupu. Uživatel vybere Allow access, nebo Deny.

Jeden udělený přístup může zahrnovat více workspace. Uživatel může seznam později změnit ve webovém rozhraní v sekci Account > Connected apps a vaše aplikace změnu uvidí při dalším požadavku.

Po schválení Emailit přesměruje na vaše URI pro přesměrování:

https://crm.acme.com/oauth/emailit/callback?code=XvRKyG5Pkplrd3xkRNaEayKkpkebEMdF&state=Jq3k9V0n2xR7bLm1&iss=https%3A%2F%2Fapi.emailit.com

Zkontrolujte, že state odpovídá uložené hodnotě a že iss je https://api.emailit.com. Kód platí 10 minut a lze ho použít jen jednou. Pokud uživatel vybere Deny, obsahuje přesměrování místo kódu error=access_denied.

Vyměňte kód za tokeny

Pošlete POST na tokenový endpoint jako application/x-www-form-urlencoded (přijímá se i JSON). Pošlete stejné redirect_uri a původní ověřovací kód:

curl https://api.emailit.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://crm.acme.com/oauth/emailit/callback \
  -d code_verifier="$CODE_VERIFIER"

curl https://api.emailit.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id="$CLIENT_ID" \
  -d code="$CODE" \
  -d redirect_uri=http://127.0.0.1:53682/callback \
  -d code_verifier="$CODE_VERIFIER"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Im9hdXRoLWhzMjU2In0…",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "XvRKyG5Pkplrd3xkRNaEayKkpkebEMdFn0h1VIuqixAOXybMtJfK8w",
  "scope": "full"
}

Přístupový token platí 15 minut (expires_in je v sekundách). Zacházejte s ním jako s neprůhledným řetězcem: neparsujte ho a nespoléhejte na jeho obsah.

Volejte API

Přístupový token používejte jako bearer token pro REST API i MCP server, přesně jako API klíč:

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

Požadavky na REST API běží ve výchozím workspace uděleného přístupu: v tom, ve kterém se uživatel rozhodl začít, nebo na který ho později změnil. Nástroje MCP mohou argumentem workspace cílit i na jiný povolený workspace. Každý požadavek používá udělené oprávnění a roli uživatele ve workspace, takže požadavek mimo rozsah oprávnění nebo volání cesty vyhrazené roli Admin uživatelem s rolí Member vrací 403. Pokud uživatel workspace opustí, přijde o něj i udělený přístup.

Obnova tokenů

Než přístupový token vyprší, nebo když požadavek vrátí 401, získejte nový:

curl https://api.emailit.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

• Výměna. Každá obnova vrací nový refresh_token platný 60 dní. Uložte ho a starý zahoďte. Dokud obnovujete do 60 dní, připojení nevyprší.
• Detekce opakovaného použití. Pokud se starý obnovovací token použije znovu déle než minutu poté, co byl nahrazen, Emailit vrátí invalid_grant (Refresh token reuse detected) a odvolá celý udělený přístup. Uživatel pak musí aplikaci autorizovat znovu. Obnovy provádějte postupně, aby dva workery nikdy nepoužily stejný obnovovací token.
• Užší oprávnění. Parametrem scope můžete získat přístupový token s užším rozsahem oprávnění, než má udělený přístup. O širší požádat nemůžete.

Odvolejte udělený přístup

Když uživatel Emailit od vaší aplikace odpojí, odvolejte udělený přístup jeho obnovovacím tokenem:

curl https://api.emailit.com/oauth/revoke \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN"

Endpoint autentizuje vašeho klienta stejně jako tokenový endpoint a vždy vrací 200 s prázdným tělem. Odvolání obnovovacího tokenu odvolá celý udělený přístup: jeho přístupové tokeny přestanou fungovat při dalším požadavku. Přístupové tokeny nelze odvolat samostatně; token_type_hint=access_token vrací invalid_request.

Uživatelé mohou přístup vaší aplikace odvolat i ze své strany na stránce Připojené aplikace ve webovém rozhraní, nebo přes API udělených přístupů popsané níže.

Spravujte udělené přístupy

API udělených přístupů vypisuje a mění udělené přístupy ze strany uživatele. Přijímá relaci uživatele ve webovém rozhraní, nebo API klíč s plným přístupem:

Každý udělený přístup v seznamu má tento tvar:

{
  "id": "9b1f6c2e-4d3a-4f8e-9a7b-2c5d8e1f0a3b",
  "client_id": "https://chatgpt.com/oauth/client.json",
  "client": { "name": "ChatGPT", "uri": "https://chatgpt.com", "logo_uri": null },
  "default_workspace": { "id": "w3f9a1c2e", "name": "Acme" },
  "workspace_access": "selected",
  "workspaces": [{ "id": "w3f9a1c2e", "name": "Acme" }],
  "scopes": ["sending", "full"],
  "resource": "https://api.emailit.com/mcp",
  "created_at": "2026-10-01T09:30:12Z",
  "revoked_at": null,
  "revoked_reason": null
}

Pokud chcete změnit workspace uděleného přístupu, pošlete access (all, nebo selected), u selected také workspace_ids a volitelně default_workspace_id, které musí patřit mezi povolené workspace:

curl -X PUT https://api.emailit.com/oauth/grants/9b1f6c2e-4d3a-4f8e-9a7b-2c5d8e1f0a3b/workspaces \
  -H "Authorization: Bearer $DASHBOARD_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "access": "selected", "workspace_ids": ["w3f9a1c2e"], "default_workspace_id": "w3f9a1c2e" }'

Uživatel musí být členem každého workspace, který vybere. Odvolaný udělený přístup nelze upravit (409); aplikace se musí připojit znovu.

Chyby

Endpointy OAuth vracejí chyby ve formátu OAuth, ne ve formátu chyb REST API:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Dokud nejsou client_id a redirect_uri ověřené, zobrazují se chyby autorizace v prohlížeči jako JSON a nikdy se nepřesměrovávají. Potom se chyby přesměrují na vaše zpětné volání (s error, error_description, state a iss) jen u loopback URI, URI s vlastním schématem a u klientů s dokumentem s metadaty; ostatní klienti dostanou chybovou stránku v JSON. Odmítnutí uživatelem přes Deny se přesměruje vždy.

Kontrolní seznam zabezpečení

• client_secret a obnovovací tokeny uchovávejte na serveru a ukládejte je šifrované. Nikdy nedávejte tajný klíč klienta do mobilní, desktopové ani prohlížečové aplikace; místo toho použijte veřejného klienta s PKCE.
• Pro každou autorizaci vygenerujte nový state a ověřovací kód a při zpětném volání zkontrolujte state a iss.
• Registrujte přesná URI pro přesměrování. Jako zpětná volání nepoužívejte otevřené přesměrovače.
• Každý udělený přístup ukládejte s workspace, ke kterému patří, a na invalid_grant reagujte tak, že uživatele požádáte o nové připojení.
• Pokud jen odesíláte e-maily, žádejte o sending.

Související