> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.xmenu.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticazione

> Metodi di autenticazione API e come utilizzarli

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 <a href="https://app.xmenu.it/restaurant/" target="_blank">pannello ristorante</a> alla voce **Strumenti > Accesso API**.

### Utilizzo

Includi l'API Key nell'header HTTP delle tue richieste:

```http theme={null}
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:

```http theme={null}
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 (<a href="https://datatracker.ietf.org/doc/html/rfc6749" target="_blank">RFC 6749</a>).

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:

```http theme={null}
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:

```json theme={null}
{
  "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:

```http theme={null}
Authorization: Bearer your-access-token
```

<Tip>
  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.
</Tip>

### 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).

<Warning>
  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.
</Warning>

#### Formato risposta errore OAuth

Gli errori OAuth utilizzano una struttura standardizzata:

```json theme={null}
{
  "error": "error_code",
  "error_description": "Descrizione leggibile dell'errore"
}
```

#### Codici errore OAuth standard

<ResponseField name="invalid_token" type="error">
  **HTTP 401** - L'access token non è valido, è scaduto o è stato revocato
</ResponseField>

<ResponseField name="insufficient_scope" type="error">
  **HTTP 403** - L'access token non ha i permessi richiesti. L'header `WWW-Authenticate` include gli scope mancanti
</ResponseField>

<ResponseField name="invalid_request" type="error">
  **HTTP 400** - La richiesta manca di parametri obbligatori, contiene valori non validi o è malformata
</ResponseField>

<ResponseField name="invalid_grant" type="error">
  **HTTP 400** - Il codice di autorizzazione o il refresh token non è valido o è scaduto (usato nell'endpoint token OAuth)
</ResponseField>

<ResponseField name="invalid_client" type="error">
  **HTTP 401** - Autenticazione client fallita (credenziali non valide nell'endpoint token OAuth)
</ResponseField>

<ResponseField name="unsupported_grant_type" type="error">
  **HTTP 400** - Il grant type non è supportato dal server di autorizzazione (usato nell'endpoint token OAuth)
</ResponseField>