OAuth 2.0 pentru aplicații

OAuth 2.0 permite unei aplicații să acceseze Planfix în numele unui utilizator fără a solicita sau stoca parola utilizatorului.

Planfix folosește fluxul Authorization Code cu PKCE S256 obligatoriu. OAuth poate fi folosit pentru conectare la REST API sau la Planfix MCP server.

Dacă doriți să conectați un client AI gata făcut, începeți cu Planfix MCP. Dacă gestionați accesul în contul dumneavoastră, vedeți Aplicații OAuth și MCP într-un cont. Partenerii și dezvoltatorii de integrări multi-conturi ar trebui să consulte Aplicații OAuth pentru parteneri.

Opțiuni de înregistrare a aplicației

Opțiune	Când să o folosiți	Unde funcționează
Aplicație deținută de cont	Integrarea este destinată unui singur cont și clientul are nevoie de un client_id predefinit.	Doar în contul care o deține.
Aplicație deținută de partener	Aceeași aplicație trebuie să se conecteze la mai multe conturi ale clienților.	În conturile în care este permisă de politica de securitate sau de un administrator.
Înregistrare automată a clientului MCP	Clientul MCP suportă un Client ID Metadata Document (CIMD) sau Dynamic Client Registration (DCR).	Înregistrarea în sine nu acordă acces la cont. Aplicația trebuie în continuare permisă în contul selectat.

CIMD și DCR sunt disponibile doar pentru conexiunile MCP. Pentru REST API, folosiți o aplicație deținută de cont sau de partener.

Endpoint-uri OAuth

Noile integrări ar trebui să utilizeze endpoint-urile globale. Numele contului nu este inclus în aceste URL-uri: utilizatorul selectează un cont în timpul autorizării.

Scop	Adresă
Issuer	https://auth.planfix.com
Authorization	https://auth.planfix.com/oauth/authorize
Token	https://auth.planfix.com/oauth/token
User information	https://auth.planfix.com/oauth/userinfo
Token revocation	https://auth.planfix.com/oauth/revoke
Dynamic MCP client registration	https://auth.planfix.com/oauth/register

Metadata serverului de autorizare este disponibilă la endpoint-urile standard:

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

Redirect URI-uri

Un redirect URI trebuie înregistrat în setările aplicației. Valoarea trimisă într-o cerere de autorizare trebuie să se potrivească cu un URI înregistrat.

Sunt permise următoarele:

• URL-uri https;
• URL-uri http doar pentru gazde loopback, cum ar fi localhost sau 127.0.0.1.

Portul poate fi dinamic pentru un URI loopback, dar schemele, gazda, calea și query-ul trebuie să coincidă. Fragmentele URL și informațiile despre utilizator din URL nu sunt permise.

Niveluri de acces

O aplicație primește doar nivelurile de acces, sau scopes, care au fost permise în prealabil. Consultați REST API access levels pentru lista completă.

Setul solicitat trebuie să fie un submult al scopurilor înregistrate pentru aplicație. Scopurile aplicației nu extind permisiunile utilizatorului în Planfix: aplicația poate accesa doar datele disponibile angajatului care a conectat-o.

Aplicațiile gestionate primesc, de asemenea, scope-urile de serviciu userinfo, openid și email.

Autorizarea utilizatorului

Generați un code_verifier și reprezentarea sa SHA-256, code_challenge, apoi deschideți endpoint-ul de autorizare într-un browser.

Exemplu REST API:

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

Pentru MCP, adăugați parametrul resource cu exact URL-ul serverului MCP:

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp

Parametru	Descriere
client_id	Identificatorul unei aplicații înregistrate. Pentru CIMD, acesta este URL-ul documentului metadata al clientului.
redirect_uri	Unul dintre redirect URI-urile permise.
response_type	Trebuie să fie code.
scope	Permisiunile cerute separate prin spațiu. Acest parametru este obligatoriu pentru REST API. Un client MCP îl poate omite, caz în care se folosesc scope-urile permise pentru aplicație.
state	O valoare aleatorie care protejează cererea de înlocuire. Aplicația trebuie să o valideze după redirect.
code_challenge	Base64url fără padding al hash-ului SHA-256 al code_verifier.
code_challenge_method	Este suportat doar S256.
resource	Pentru MCP, URL-ul exact https://mcp.planfix.com/mcp. Nu trimiteți acest parametru pentru REST API.

Utilizatorul selectează un cont, se autentifică și examinează permisiunile solicitate. O aplicație deținută de cont își deschide direct contul proprietar. Dacă politica de securitate cere aprobarea unui administrator, Planfix afișează pasul corespunzător. Un administrator poate aproba aplicația și o poate conecta într-o singură acțiune.

După autorizare reușită, Planfix redirecționează browserul la redirect_uri:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Un authorization code se folosește o singură dată și rămâne valabil 10 minute.

Obținerea tokenurilor

Trimiteți o cerere POST la /oauth/token folosind application/x-www-form-urlencoded:

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

Pentru MCP, repetați parametrul resource cu aceeași valoare folosită în cererea de autorizare.

Un client public trimite cererea fără secret. Un client confidențial se autentifică de asemenea folosind client_secret_basic sau parametrii client_id și client_secret în corpul cererii.

Exemplu de răspuns:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Pentru REST API, răspunsul conține și account_name, account_domain și account_url. Stocați aceste valori și folosiți URL-ul contului selectat pentru cererile REST API.

Un access token este valabil 24 de ore. Este legat de utilizator, cont, aplicație, scope-uri și resource. Un token emis pentru MCP nu poate fi folosit direct cu REST API, iar un token REST API nu poate fi folosit cu MCP.

Utilizarea unui token cu REST API

Trimiteți tokenul în header-ul Authorization:

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Folosiți URL-ul contului returnat când codul de autorizare a fost schimbat pentru tokenuri. Sunt disponibile doar metodele acoperite de scope-urile acordate. Tokenurile OAuth sunt supuse planului contului și limitelor standard REST API limits.

Informații despre utilizator

Cererea userinfo necesită scope-ul openid:

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Exemplu de răspuns când scope-ul email este prezent:

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Autorizarea OAuth globală este disponibilă angajaților contului. Planfix nu emite un id_token; solicitați datele utilizatorului prin userinfo în schimb.

Reînnoirea tokenurilor

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

Pentru MCP, trimiteți din nou același resource. Un client confidențial trebuie să se autentifice folosind secretul său.

Planfix returnează un nou access token și un nou refresh token. Refresh tokenul anterior devine invalid imediat, deci aplicația trebuie să înlocuiască valoarea stocată atomic.

Revocarea unui token

Un client poate revoca un refresh token prin /oauth/revoke:

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Un utilizator poate, de asemenea, să elimine o conexiune din secțiunea Session management din fișa sa de utilizator. Un administrator poate revoca aprobarea unei aplicații terțe pentru întreg contul. Vezi Aplicații OAuth și MCP într-un cont.

Compatibilitate cu integrările existente

Endpoint-urile tenant, precum https://account.planfix.com/api/v2/oauth/authorize, /token și /userinfo continuă să funcționeze pentru integrările existente legate de un cont specific.

Folosiți endpoint-urile globale pentru integrările noi. Acestea suportă descoperirea metadata standard, selecția contului și MCP. Nu combinați endpoint-urile globale și tenant în aceeași sesiune OAuth.

Recomandări de securitate

• Folosiți întotdeauna PKCE S256 și validați state.
• Folosiți un client public fără secret pentru aplicații mobile, desktop și în browser.
• Folosiți un client confidențial doar când secretul poate fi stocat în siguranță pe un server.
• Solicitați setul minim necesar de scope-uri.
• Nu scrieți access tokenuri, refresh tokenuri, coduri de autorizare, code_verifier sau secretele clientului în loguri.
• Stocați refresh tokenurile și secretele clientului în stocare criptată.
• Validați iss în răspuns și acceptați numai issuer-ul Planfix așteptat.

Erori posibile

Eroare	Cauză
invalid_client	Clientul este necunoscut sau dezactivat, secretul clientului este incorect, sau aplicația nu este disponibilă în contul selectat.
invalid_grant	Codul de autorizare sau refresh tokenul este invalid, expirat, deja folosit, sau nu corespunde clientului, redirect URI-ului, datelor PKCE sau resource-ului.
invalid_scope	Cererea conține un scope care nu este permis pentru aplicație.
invalid_target	resource este nesuportat sau s-a schimbat între cereri.
access_denied	Utilizatorul a refuzat conexiunea sau politica contului nu permite aplicația.
HTTP 401, invalid_token	Access tokenul este necunoscut, expirat sau revocat.
HTTP 403, insufficient_scope	Tokenul nu conține scope-ul necesar pentru operațiune.

Mergeți la

• Planfix MCP
• Aplicații OAuth și MCP într-un cont
• Aplicații OAuth pentru parteneri
• REST API
• REST API Authorization
• REST API: Access Levels List – scope