Autenticazione

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

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:

aud_acc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Header di autenticazione

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

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

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

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

Prossimo passo

Con l'autenticazione pronta, vedi Formato risposte & convenzioni per capire la shape delle risposte e degli errori.