Přejít na hlavní obsah
Twenty implementuje OAuth 2.0 s autorizačním kódem + PKCE pro aplikace pro uživatele a přihlašovací údaje klienta pro přístup server-to-server. Klienti se registrují dynamicky přes RFC 7591 — žádné ruční nastavení v dashboardu.

​
Kdy použít OAuth

ScénářMetoda ověřování
Interní skripty, automatizaceKlíč API
Externí aplikace jednající jménem uživateleOAuth — autorizační kód
Server-to-server, bez uživatelského kontextuOAuth — přihlašovací údaje klienta
Aplikace Twenty s rozšířeními uživatelského rozhraníAplikace (OAuth je řešen automaticky)

​
Registrace klienta

Twenty podporuje dynamickou registraci klienta podle RFC 7591. Není potřeba žádné ruční nastavení — registrujte programově: 
POST /oauth/register
Content-Type: application/json

{
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "client_secret_post"
}
Odpověď: 
{
  "client_id": "abc123",
  "client_secret": "secret456",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"]
}
Uložte client_secret bezpečně — později jej nelze získat zpět.

​
Oprávnění

OprávněníPřístup
apiÚplný přístup pro čtení i zápis k API Core a Metadata
profileČtení informací o profilu ověřeného uživatele
Vyžádejte oprávnění jako řetězec oddělený mezerami: scope=api profile

​
Tok s autorizačním kódem

Tento tok použijte, když vaše aplikace jedná jménem uživatele Twenty.

​
1. Přesměrujte uživatele k autorizaci

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=https://myapp.com/callback&
  scope=api&
  state=random_state_value&
  code_challenge=CHALLENGE&
  code_challenge_method=S256
ParametrPovinnéPopis
client_idAnoVaše registrované ID klienta
response_typeAnoMusí být code
redirect_uriAnoMusí odpovídat registrované adrese URI pro přesměrování
scopeNeOprávnění oddělená mezerami (výchozí je api)
stateDoporučenoNáhodný řetězec k prevenci útoků CSRF
code_challengeDoporučenoVýzva PKCE (hash SHA-256 z verifieru, kódovaný jako base64url)
code_challenge_methodDoporučenoPři použití PKCE musí být S256
Uživatel uvidí souhlasovou obrazovku a přístup schválí nebo zamítne.

​
2. Zpracujte callback

Po autorizaci Twenty přesměruje zpět na vaše redirect_uri: 
https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
Ověřte, že state odpovídá tomu, co jste poslali.

​
3. Vyměňte kód za tokeny

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://myapp.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=YOUR_PKCE_VERIFIER
Odpověď: 
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh..."
}

​
4. Použijte přístupový token

GET /rest/companies
Authorization: Bearer ACCESS_TOKEN

​
5. Obnovte po vypršení platnosti

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

​
Tok s přihlašovacími údaji klienta

Pro integrace server-to-server bez interakce uživatele: 
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=api
Vrácený token má přístup na úrovni pracovního prostoru, není vázán na žádného konkrétního uživatele.

​
Zjišťování serveru

Twenty zveřejňuje svou konfiguraci OAuth na standardním koncovém bodu pro zjišťování: 
GET /.well-known/oauth-authorization-server
Vrací všechny koncové body, podporované typy grantů, oprávnění a možnosti — užitečné pro tvorbu obecných klientů OAuth.

​
Přehled koncových bodů API

Koncový bodÚčel
/.well-known/oauth-authorization-serverZjišťování metadat serveru
/oauth/registerDynamická registrace klienta
/oauth/authorizeAutorizace uživatele
/oauth/tokenVýměna a obnovení tokenu
ProstředíZákladní URL
Cloudhttps://api.twenty.com
Vlastní hostinghttps://{your-domain}

​
OAuth vs klíče API

API KlíčeOAuth
NastaveníGenerovat v NastaveníZaregistrovat klienta, implementovat tok
Uživatelský kontextŽádný (na úrovni pracovního prostoru)Oprávnění konkrétního uživatele
Vhodné proSkripty, interní nástrojeExterní aplikace, víceuživatelské integrace
Rotace tokenůRučníAutomaticky prostřednictvím refresh tokenů
Přístup podle oprávněníPlný přístup k APIJemně odstupňovaný pomocí oprávnění