Vai al contenuto principale
L’API xMenu supporta tre metodi di autenticazione, ciascuno progettato per diversi casi d’uso e requisiti di sicurezza.

​
API Key

Metodo di autenticazione che fornisce accesso alle funzionalità principali dell’API.

​
Come ottenerla

Puoi trovare la tua API Key nel pannello ristorante alla voce Strumenti > Accesso API.

​
Utilizzo

Includi l’API Key nell’header HTTP delle tue richieste: 
X-Api-Key: your-api-key

​
API Client

Autenticazione avanzata che consente l’accesso completo a tutte le funzionalità dell’API, incluse Importazione Menu e Inserimento Ordini.

​
Come ottenerle

Contatta il nostro staff di supporto per richiedere le tue credenziali API Client (Client ID e Client Secret).

​
Utilizzo

Includi entrambe le credenziali negli header HTTP delle tue richieste: 
X-Client-Id: your-client-id
X-Client-Secret: your-client-secret

​
API Client + OAuth 2.0

Autenticazione avanzata tramite credenziali API Client con lo standard di sicurezza OAuth 2.0 (RFC 6749). Questo metodo implementa il grant type Client Credentials, progettato per l’autenticazione server-to-server dove il client agisce per proprio conto.

​
Flusso di autenticazione

1. Richiedi un access token Effettua una richiesta POST all’endpoint token con le tue credenziali API Client: 
POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your-client-id
&client_secret=your-client-secret
2. Ricevi l’access token Il server risponde con un access token: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
3. Utilizza il token nelle richieste API Includi l’access token nell’header Authorization di tutte le richieste successive: 
Authorization: Bearer your-access-token
Gli access token hanno una validità limitata (indicata da expires_in in secondi). Implementa una logica di refresh per richiedere un nuovo token prima della scadenza.

​
Risposte di errore con OAuth

Quando si utilizza l’autenticazione OAuth 2.0 con Bearer token, tutte le risposte di errore con stato HTTP 400, 401 o 403 vengono restituite in formato conforme a OAuth secondo RFC 6749 (OAuth 2.0) e RFC 6750 (Bearer Token Usage).
Il formato errore OAuth viene utilizzato per tutti gli errori API (non solo errori di autenticazione) quando la richiesta utilizza l’autenticazione OAuth Bearer token e restituisce uno stato 400, 401 o 403.

​
Formato risposta errore OAuth

Gli errori OAuth utilizzano una struttura standardizzata: 
{
  "error": "error_code",
  "error_description": "Descrizione leggibile dell'errore"
}

​
Codici errore OAuth standard

​
invalid_token
error
HTTP 401 - L’access token non è valido, è scaduto o è stato revocato
​
insufficient_scope
error
HTTP 403 - L’access token non ha i permessi richiesti. L’header WWW-Authenticate include gli scope mancanti
​
invalid_request
error
HTTP 400 - La richiesta manca di parametri obbligatori, contiene valori non validi o è malformata
​
invalid_grant
error
HTTP 400 - Il codice di autorizzazione o il refresh token non è valido o è scaduto (usato nell’endpoint token OAuth)
​
invalid_client
error
HTTP 401 - Autenticazione client fallita (credenziali non valide nell’endpoint token OAuth)
​
unsupported_grant_type
error
HTTP 400 - Il grant type non è supportato dal server di autorizzazione (usato nell’endpoint token OAuth)