---
title: Autenticazione
description: Ottieni l'Account API Key, autenticati con l'header X-API-Key e comprendi cosa implica l'accesso account-level.
---

L'API REST partner usa una sola credenziale: l'**Account API Key**. La invii
nell'header `X-API-Key` su ogni richiesta. Non ci sono token da rinnovare né
flussi OAuth: la chiave è di lunga durata e ha accesso completo alle risorse del
tuo Account.

## Più chiavi per Account

Un Account può avere **più API Key contemporaneamente**. Ogni chiave è
indipendente, autentica da sola e ha:

- una **etichetta** (label) che scegli tu per riconoscerla (es. "Backend
  produzione", "Integrazione gestionale", "Test");
- una **data di creazione**;
- una **scadenza opzionale** — se la imposti, la chiave smette di autenticare
  (`401`) dopo quella data; se non la imposti, la chiave **non scade mai**;
- uno **stato** (attiva / scaduta / revocata).

Avere più chiavi ti permette di assegnarne una a ciascuna integrazione e di
**revocarne una sola** (per esempio se sospetti che sia stata compromessa o se
dismetti un'integrazione) senza interrompere le altre.

## Creare un'API Key

<Steps>
<Step>
Accedi al dashboard: [app.audin.ai](https://app.audin.ai).
</Step>

<Step>
Vai su **Settings → Developer → API Keys**.
</Step>

<Step>
Clicca **Crea API key**, dai un'**etichetta** alla chiave e, se vuoi, imposta una
**data di scadenza** (lasciala vuota perché la chiave non scada mai).
</Step>

<Step>
**Copia la chiave subito.** Il valore completo viene mostrato una sola volta, al
momento della creazione, e non è più recuperabile dopo. Conservalo in un secret
manager o in una variabile d'ambiente.
</Step>
</Steps>

Nell'elenco delle chiavi vedi label, data di creazione, scadenza, stato e
**data di ultimo utilizzo** di ognuna; il valore completo della chiave **non** è
più visibile dopo la creazione (ne resta solo un riferimento parziale per
riconoscerla).

La chiave ha il formato:

```text
aud_acc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Header di autenticazione

Includi la chiave nell'header `X-API-Key` su **ogni** richiesta:

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
curl https://api.audin.ai/leads \
  -H "X-API-Key: $API_KEY"
```

</Tab>
<Tab value="JavaScript">

```js
const res = await fetch("https://api.audin.ai/leads", {
  headers: {
    "X-API-Key": process.env.AUDIN_API_KEY,
  },
});
const leads = await res.json();
```

</Tab>
</Tabs>

## Cosa implica l'accesso account-level

L'Account API Key non è una credenziale "ristretta": comportati di conseguenza
quando la custodisci.

- **Legata a un singolo Account.** Audin è multi-tenant; una chiave opera
  esclusivamente sulle risorse del proprio Account. Non esiste accesso
  cross-account.
- **Accesso admin-equivalent.** La chiave può leggere e scrivere **tutte** le
  risorse dell'Account a cui appartiene.
- **Permessi granulari bypassati.** Il controllo per ruolo/permesso del dashboard
  **non si applica** all'API Key: qualunque chiamata è consentita purché la
  risorsa appartenga all'Account. Se serve un accesso più granulare, gestiscilo
  nel tuo backend prima di chiamare l'API.
- **Foreign-key utente risolte automaticamente.** Le scritture che richiedono un
  riferimento a un utente piattaforma (es. `createdBy`, `ownerId`) vengono
  risolte automaticamente sull'owner dell'Account: non devi (e non puoi) passare
  un id utente.

## Capire quale chiave ha fatto cosa

Nel **log delle chiamate API** (dashboard → **Settings → Developer**) ogni
richiesta riporta **quale API Key** l'ha effettuata, oltre all'esito e
all'istante. Combinato con la **data di ultimo utilizzo** mostrata nell'elenco
delle chiavi, questo ti permette di capire se una chiave è ancora in uso prima
di revocarla, e di attribuire il traffico a una specifica integrazione.

## Revocare una chiave

Revoca una chiave dal dashboard (**Settings → Developer → API Keys**) non appena
non è più necessaria — ad esempio se sospetti che sia stata compromessa. La
revoca agisce **sulla singola chiave**: le altre chiavi dell'Account continuano a
funzionare. Una chiave revocata smette immediatamente di autenticare (le
richieste ricevono `401`).

<Callout type="warn">
  **L'API Key è un segreto. Trattala come una password.**

  - Usala **solo lato server** (backend, job, agent server-to-server). **Mai** in
    un browser, in un'app mobile o in qualunque client pubblico: chiunque acceda
    al codice client otterrebbe accesso completo al tuo Account.
  - Conservala in un **secret manager** o in una variabile d'ambiente
    (`process.env.AUDIN_API_KEY`), mai hardcoded nel sorgente o in un repository.
  - Se ti serve far operare un client (es. il browser di un operatore), non
    distribuire l'API Key: usa un flusso token-effimero lato server.
</Callout>

## Prossimo passo

Con l'autenticazione pronta, vedi
[Formato risposte & convenzioni](/docs/api-rest/formato-e-convenzioni) per capire
la shape delle risposte e degli errori.