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

# Authentication

> API authentication methods and how to use them

The xMenu API supports three authentication methods, each designed for different use cases and security requirements.

## API Key

Authentication method that provides access to core API functionalities.

### How to obtain

You can find your API Key in the <a href="https://app.xmenu.it/restaurant/" target="_blank">restaurant panel</a> under **Tools > API Access**.

### Usage

Include the API Key in the HTTP header of your requests:

```http theme={null}
X-Api-Key: your-api-key
```

## API Client

Advanced authentication that enables full access to all API functionalities, including Menu Import and Order Insertion.

### How to obtain

Contact our support staff to request your API Client credentials (`Client ID` and `Client Secret`).

### Usage

Include both credentials in the HTTP headers of your requests:

```http theme={null}
X-Client-Id: your-client-id
X-Client-Secret: your-client-secret
```

## API Client + OAuth 2.0

Advanced authentication using API Client credentials with the OAuth 2.0 security standard (<a href="https://datatracker.ietf.org/doc/html/rfc6749" target="_blank">RFC 6749</a>).

This method implements the **Client Credentials** grant type, which is designed for server-to-server authentication where the client acts on its own behalf.

### Authentication flow

**1. Request an access token**

Make a POST request to the token endpoint with your API Client credentials:

```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. Receive the access token**

The server responds with an access token:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

**3. Use the token in API requests**

Include the access token in the `Authorization` header of all subsequent requests:

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

<Tip>
  Access tokens have a limited validity period (indicated by `expires_in` in seconds). Implement token refresh logic to request a new token before expiration.
</Tip>

### Error responses with OAuth

When using OAuth 2.0 Bearer token authentication, **all error responses with HTTP status 400, 401, or 403** are returned in OAuth-compliant format according to RFC 6749 (OAuth 2.0) and RFC 6750 (Bearer Token Usage).

<Warning>
  The OAuth error format is used for **all API errors** (not just authentication errors) when the request uses OAuth Bearer token authentication and returns a 400, 401, or 403 status code.
</Warning>

#### OAuth error response format

OAuth errors use a standardized structure:

```json theme={null}
{
  "error": "error_code",
  "error_description": "Human-readable description of the error"
}
```

#### Standard OAuth error codes

<ResponseField name="invalid_token" type="error">
  **HTTP 401** - The access token is invalid, expired, or has been revoked
</ResponseField>

<ResponseField name="insufficient_scope" type="error">
  **HTTP 403** - The access token does not have the required permissions. The `WWW-Authenticate` header includes the missing scopes
</ResponseField>

<ResponseField name="invalid_request" type="error">
  **HTTP 400** - The request is missing required parameters, contains invalid values, or is malformed
</ResponseField>

<ResponseField name="invalid_grant" type="error">
  **HTTP 400** - The authorization code or refresh token is invalid or expired (used in OAuth token endpoint)
</ResponseField>

<ResponseField name="invalid_client" type="error">
  **HTTP 401** - Client authentication failed (invalid credentials in OAuth token endpoint)
</ResponseField>

<ResponseField name="unsupported_grant_type" type="error">
  **HTTP 400** - The grant type is not supported by the authorization server (used in OAuth token endpoint)
</ResponseField>