Saltar al contingut principal

Autenticació de l'API de plataforma (JWT)

L'API REST de vitalera utilitza autenticació JWT (JSON Web Token) basada en l'estàndard OAuth 2.0.

Obtenció de credencials​

Contacteu amb [email protected] per sol·licitar:

  • Client ID — identifica la vostra aplicació
  • Client Secret — autentica la vostra aplicació
  • Application ID — utilitzat per a la rotació de credencials

Client Credentials Grant​

Per a integracions servidor a servidor (màquina a màquina):

curl -X POST "https://api.vitalera.io/api/auth/tokens/" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "client_credentials",
           "client_id": "<CLIENT_ID>",
           "client_secret": "<CLIENT_SECRET>"
         }'

Resposta:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Password Grant​

Per a fluxos d'inici de sessió d'usuari (p. ex., apps mòbils o web que autentiquen usuaris individuals):

curl -X POST "https://api.vitalera.io/api/auth/tokens/" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "password",
           "username": "<USERNAME>",
           "password": "<PASSWORD>"
         }'

Resposta:

{
  "id_token": "<ID_TOKEN>",
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "sub": "<USER_ID>"
}

Fent peticions a l'API​

Incloeu el token d'accés a la capçalera Authorization de cada petició:

curl -X GET "https://api.vitalera.io/api/plans/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Validesa del token​

Els tokens d'accés són vàlids durant 1 hora (3600 segons). Quan un token expira, l'API retorna HTTP 401 Unauthorized:

{
  "errors": [
    {
      "errorType": "expired_token",
      "message": "Access token expired"
    }
  ]
}

Refresc de token​

Si heu obtingut un refresh token (mitjançant password grant), podeu refrescar el vostre token d'accés sense tornar a autenticar-vos:

curl -X POST "https://api.vitalera.io/api/auth/tokens/refresh/" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
           "refresh_token": "<REFRESH_TOKEN>"
         }'

Validació de token​

Verifiqueu que un token encara és vàlid:

curl -X GET "https://api.vitalera.io/api/auth/tokens/validate/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Rotació de credencials​

Per seguretat, roteu periòdicament les vostres credencials de client. Això requereix un JWT vàlid i l'application_id:

curl -X POST "https://api.vitalera.io/api/applications/rotate_credentials/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "application_id": "<APPLICATION_ID>"
         }'

Resposta:

{
  "id": "<APPLICATION_ID>",
  "name": "TestApp",
  "organization": "123",
  "client_id": "<NEW_CLIENT_ID>",
  "client_secret": "<NEW_CLIENT_SECRET>",
  "application_types": ["API"]
}

Després de la rotació, les credencials anteriors s'invaliden immediatament.

Necessiteu ajuda?​

Contacteu amb [email protected] per a assistència amb la configuració d'autenticació.