Skip to main content

Autentificare

PayLinks folosește JWT bearer token-uri pentru autentificarea API.

  • Pentru web: magic link sau Google OAuth.
  • Pentru integrări/agenți AI: creezi chei API în Dashboard Profile, apoi le schimbi pentru JWT-uri short-lived.

Flux API Key (Recomandat pentru Integrări)​

Acest flux este gândit pentru server-to-server și agenți AI.

0. (Opțional) Înregistrare programatică într-un singur request​

Dacă dezvoltatorul nu are deja cont PayLinks:

curl -X POST https://api.paylinks.ro/api/v1/auth/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Dev","keyName":"Primary integration"}'

Răspunsul include contul, prima cheie API și un JWT short-lived.

1. Creează o cheie API în Dashboard​

Intră în Dashboard -> Profile -> API Access și creează o cheie.

Primești:

  • keyId (prefix plk_)
  • keySecret (prefix pls_, afișat o singură dată)

2. Schimbă cheia API pentru JWT​

curl -X POST https://api.paylinks.ro/api/v1/auth/api/token \
  -H "Content-Type: application/json" \
  -d '{"keyId":"plk_xxx","keySecret":"pls_xxx"}'
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresInSeconds": 3600,
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "role": "USER"
  }
}

3. Folosește JWT-ul ca Bearer token​

curl https://api.paylinks.ro/api/v1/paylinks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Currency: RON"
curl -X POST https://api.paylinks.ro/api/v1/auth/request \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
{"ok": true}

2. Utilizatorul dă click pe linkul din email​

Email-ul conține un link care trimite către endpoint-ul de verificare cu parametrul token în query string.

3. Verifică și obține JWT​

curl "https://api.paylinks.ro/api/v1/auth/verify?token=MAGIC_TOKEN"
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "needsOnboarding": false
}

Fluxul Google OAuth​

OAuth standard​

  1. Redirecționează utilizatorul către: GET /auth/google/start?redirectTo=https://yourapp.com/callback
  2. Utilizatorul completează consimțământul Google
  3. Google redirecționează către /auth/google/callback cu code și state
  4. API-ul returnează un JWT token

Google One Tap​

curl -X POST https://api.paylinks.ro/api/v1/auth/google/onetap \
  -H "Content-Type: application/json" \
  -d '{"credential": "GOOGLE_ONE_TAP_JWT"}'

Utilizarea token-ului​

Include JWT-ul în header-ul Authorization pentru toate endpoint-urile protejate:

curl https://api.paylinks.ro/api/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Header-ul X-Currency​

Setează contextul valutar cu header-ul X-Currency:

curl https://api.paylinks.ro/api/v1/paylinks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Currency: EUR"

Valori suportate: RON (implicit), EUR, GBP.

Acest header influențează moneda folosită la crearea linkurilor de plată și modul în care sunt returnate valorile monetare.

Ciclul de viață al token-ului​

ProprietateValoare
TipJWT (JSON Web Token)
Expirare (magic link / Google)7 zile
Expirare (API key exchange)1 oră
AlgoritmHS256
RevocareIncrementează tokenVersion al utilizatorului pentru a invalida toate token-urile

Token-urile sunt stateless. Nu există un flux de refresh token — solicită un nou magic link sau re-autentifică-te prin Google OAuth când token-ul expiră.

Răspunsuri de eroare​

Token lipsă sau invalid:

{
  "error": {
    "message": "Unauthorized",
    "code": "UNAUTHORIZED"
  }
}

Status HTTP: 401

Întrebări frecvente​

Cât durează token-urile JWT?​

Token-urile JWT PayLinks din magic link / Google expiră după 7 zile. Token-urile JWT obținute din API key exchange expiră după 1 oră.

Când token-ul expiră:

  • Flux web: solicită un nou magic link sau re-autentifică-te prin Google OAuth.
  • Flux API: rulează din nou POST /auth/api/token cu keyId + keySecret.

Cum revoc un token?​

Pentru a invalida toate token-urile unui utilizator, incrementează câmpul tokenVersion al utilizatorului. Aceasta revocă imediat fiecare JWT emis anterior pentru acel cont, forțând re-autentificarea.

Ce se întâmplă când token-ul meu expiră?​

Cererile API cu un token expirat returnează un răspuns 401 Unauthorized cu codul de eroare UNAUTHORIZED. Aplicația ta ar trebui să capteze această eroare și să redirecționeze utilizatorul către re-autentificare prin magic link sau Google OAuth.