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, automatizace | Klíč API |
| Externí aplikace jednající jménem uživatele | OAuth — autorizační kód |
| Server-to-server, bez uživatelského kontextu | OAuth — 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"
}
{
"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 |
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
| Parametr | Povinné | Popis |
|---|
client_id | Ano | Vaše registrované ID klienta |
response_type | Ano | Musí být code |
redirect_uri | Ano | Musí odpovídat registrované adrese URI pro přesměrování |
scope | Ne | Oprávnění oddělená mezerami (výchozí je api) |
state | Doporučeno | Náhodný řetězec k prevenci útoků CSRF |
code_challenge | Doporučeno | Výzva PKCE (hash SHA-256 z verifieru, kódovaný jako base64url) |
code_challenge_method | Doporučeno | Při použití PKCE musí být S256 |
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
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
{
"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
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
Přehled koncových bodů API
| Koncový bod | Účel |
|---|
/.well-known/oauth-authorization-server | Zjišťování metadat serveru |
/oauth/register | Dynamická registrace klienta |
/oauth/authorize | Autorizace uživatele |
/oauth/token | Výměna a obnovení tokenu |
| Prostředí | Základní URL |
|---|
| Cloud | https://api.twenty.com |
| Vlastní hosting | https://{your-domain} |
OAuth vs klíče API
| API Klíče | OAuth |
|---|
| 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é pro | Skripty, interní nástroje | Externí 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 API | Jemně odstupňovaný pomocí oprávnění |
