Autenticazione

Overview

Le API Salabam Solutions utilizzano l'autenticazione JWT (JSON Web Token) per garantire la sicurezza degli accessi.

Credenziali

Per iniziare avrai bisogno di:

Client ID: Identificativo univoco del tuo sistema
Client Secret: Chiave segreta (da mantenere privata)
API Base URL: https://api.salabam.solutions/v3

Sicurezza

Non esporre mai il client_secret in codice client-side o in ambienti non sicuri.

Ottenere un token

Request

POST /auth/login
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Response (200 OK)

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200e3b4f...",
  "scope": "read write"
}

Utilizzare il token

Includi il token in ogni richiesta API:

GET /beneficiaries
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

Refresh del token

Quando il token scade (dopo 1 ora), utilizza il refresh token:

Request

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "def50200e3b4f..."
}

Response (200 OK)

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Logout

Per invalidare un token:

POST /auth/logout
Authorization: Bearer your_access_token

Gestione errori

Token scaduto (401)

{
  "error": "token_expired",
  "message": "Il token è scaduto",
  "code": 401
}

Token non valido (401)

{
  "error": "invalid_token", 
  "message": "Token non valido o malformato",
  "code": 401
}

Credenziali non valide (401)

{
  "error": "invalid_credentials",
  "message": "Client ID o secret non validi",
  "code": 401
}

Sicurezza e best practices

✅ Cosa fare

Conservare client_secret in variabili d'ambiente
Implementare il refresh automatico dei token
Utilizzare HTTPS per tutte le comunicazioni
Implementare retry logic per errori temporanei

❌ Cosa evitare

Non hard-codare credenziali nel codice
Non condividere token tra sistemi diversi
Non ignorare la scadenza dei token
Non loggare token nei file di log

Esempio completo

class SalabamAuth {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.accessToken = null;
    this.refreshToken = null;
  }

  async login() {
    const response = await fetch('https://api.salabam.solutions/v3/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        client_id: this.clientId,
        client_secret: this.clientSecret
      })
    });

    const data = await response.json();
    this.accessToken = data.access_token;
    this.refreshToken = data.refresh_token;

    return data;
  }

  async makeAuthenticatedRequest(url, options = {}) {
    if (!this.accessToken) {
      await this.login();
    }

    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json'
      }
    });

    // Auto-refresh se token scaduto
    if (response.status === 401) {
      await this.refreshAccessToken();
      return this.makeAuthenticatedRequest(url, options);
    }

    return response;
  }
}