Autenticazione

Le API di Askme Sign supportano due modalità di autenticazione: API Key (header HTTP) e OAuth 2.0 (token JWT tramite Keycloak). La modalità API Key è il metodo più diretto per integrazioni server-to-server.

---

Metodo 1: API Key (Header HTTP)

Il metodo principale di autenticazione prevede l'invio di due header HTTP in ogni richiesta:

Header	Obbligatorio	Descrizione
X-SignToken	Sì	Token API fornito dall'amministratore del tenant
X-SignUser	Sì	Username o identificativo dell'utente che esegue l'operazione

GET /api/v2/account HTTP/1.1
Host: sign.askme.it
X-SignToken: 8GvIU4U1xZ36VXbxOVwxgU1jBgFlPQBPWbUZ
X-SignUser: A462252

Come ottenere le credenziali

1. Accedere al portale Askme Sign con un utente amministratore
2. Navigare in Configurazione > API Keys
3. Creare una nuova API Key associandola all'utente desiderato
4. Copiare il token generato (X-SignToken) e lo username associato (X-SignUser)

Sicurezza

Il token API ha gli stessi permessi dell'utente a cui è associato. Conservarlo in modo sicuro (variabili d'ambiente, secret manager) e non condividerlo in codice sorgente o repository pubblici.

Esempio: cURL

curl -X GET "https://sign.askme.it/api/v2/account" \
  -H "X-SignToken: your-api-token" \
  -H "X-SignUser: your-username"

Esempio: Python (requests)

import requests

BASE_URL = "https://sign.askme.it/api/v2"
HEADERS = {
    "X-SignToken": "your-api-token",
    "X-SignUser": "your-username",
    "Content-Type": "application/json"
}

response = requests.get(f"{BASE_URL}/account", headers=HEADERS)
response.raise_for_status()
print(response.json())

Esempio: JavaScript (fetch)

const BASE_URL = 'https://sign.askme.it/api/v2';
const HEADERS = {
  'X-SignToken': 'your-api-token',
  'X-SignUser': 'your-username',
  'Content-Type': 'application/json'
};

const response = await fetch(`${BASE_URL}/account`, { headers: HEADERS });
const data = await response.json();
console.log(data);

Esempio: Java (HttpClient)

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sign.askme.it/api/v2/account"))
    .header("X-SignToken", "your-api-token")
    .header("X-SignUser", "your-username")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

---

Metodo 2: OAuth 2.0 (Keycloak)

Per integrazioni che richiedono il flusso OAuth 2.0, Askme Sign supporta l'autenticazione tramite Client Credentials con il server Keycloak centrale.

Token endpoint

POST https://account.askmesuite.com/realms/askmesuite/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

Parametri (form data)

Parametro	Valore	Descrizione
grant_type	client_credentials	Tipo di grant OAuth 2.0
client_id	string	Client ID fornito dall'amministratore
client_secret	string	Client secret associato

Esempio: cURL

curl -X POST "https://account.askmesuite.com/realms/askmesuite/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Risposta (successo)

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

Uso del token nelle API

Dopo aver ottenuto l'access_token, includerlo nell'header Authorization:

GET /api/v2/account HTTP/1.1
Host: sign.askme.it
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI...

Validazione JWT (JWKs)

Per validare lato server le firme dei JWT, usare il JWKS endpoint:

https://account.askmesuite.com/realms/askmesuite/protocol/openid-connect/certs

---

Errori di autenticazione

Codice HTTP	Descrizione	Causa
401	Unauthorized	Token API mancante, non valido o scaduto. Verificare gli header X-SignToken e X-SignUser.
403	Forbidden	Utente autenticato ma non autorizzato per l'operazione richiesta. Verificare i permessi dell'utente.

Esempio di errore

{
  "status": 401,
  "details": "Token non valido o scaduto",
  "messageKey": "error.unauthorized",
  "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-01-15T10:30:00+01:00",
  "type": "common"
}

---

Consigli di sicurezza

1. Conservare le credenziali in modo sicuro: usare variabili d'ambiente o secret manager, mai in codice sorgente
2. Usare HTTPS: tutte le comunicazioni con l'API devono avvenire su HTTPS
3. Ruotare periodicamente le API Key: rigenerare i token periodicamente
4. Principio del minimo privilegio: assegnare all'utente API solo i permessi strettamente necessari
5. Monitorare l'uso: controllare i log di accesso per rilevare utilizzi anomali