API Keys API #

Questi endpoint ti consentono di gestire le chiavi API del tuo account tramite codice. Operano tutti esclusivamente sulle chiavi dell’account chiamante.

Esistono due tipi di chiavi, che risiedono su percorsi separati:

• La tua chiave principale — l’unica chiave con accesso completo disponibile in Impostazioni → Integrazioni → Chiave API. Puoi visualizzarne l’anteprima mascherata, controllare l’utilizzo del limite di frequenza, ruotarla o revocarla. Questi sono gli endpoint /api-keys/current, /api-keys/rotate e /api-keys/usage qui sotto.
• Chiavi con ambito limitato (Scoped keys) — chiavi aggiuntive e denominate che crei per un compito specifico, ciascuna limitata alle parti dell’API che scegli. Questi sono gli endpoint /api-keys e /api-keys/{id} nella sezione Chiavi con ambito limitato. Nulla cambia per la tua chiave principale quando ne crei una; le integrazioni esistenti continuano a funzionare senza modifiche.

Tutti i percorsi seguenti sono relativi all’URL di base dell’API:

https://api.youraiconnector.com/v1

Ogni richiesta deve essere autenticata. Consulta Autenticazione per i quattro metodi accettati. Gli esempi qui utilizzano l’intestazione X-API-Key (e una forma di parametro di query per cURL).

Leggi prima questo. La rotazione o la revoca della chiave ha effetto immediato. Nel momento in cui una delle due chiamate ha successo, la vecchia chiave smette di funzionare: ogni integrazione che la utilizza ancora inizierà a ricevere errori 401. Pianifica l’operazione: esegui la rotazione durante una finestra di manutenzione e aggiorna immediatamente tutte le tue integrazioni.

Ottieni i metadati della chiave corrente #

Restituisce la tua chiave attiva: la chiave completa in api_key quando esiste una copia recuperabile, un’anteprima mascherata (i primi 4 e gli ultimi 4 caratteri) e, quando disponibile, la data di creazione. api_key è null per le chiavi create prima che venissero conservate le copie recuperabili: esegui una rotazione una volta e la nuova chiave potrà essere mostrata di nuovo in seguito.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

Se l’account non dispone di una chiave API, la risposta è 404 con { "success": false, "error": "No API key found for this account" }.

Ottieni l’utilizzo del limite di frequenza #

Restituisce l’utilizzo del limite di frequenza per la finestra corrente: il limite di richieste per finestra, quante richieste sono state conteggiate finora, quante ne rimangono e quando la finestra si resetta. Utilizza queste informazioni per implementare una limitazione lato client, in modo che la tua integrazione rallenti prima di raggiungere le risposte 429.

GET /api-keys/usage

cURL

curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Se non sono ancora state registrate richieste nella finestra corrente, l’utilizzo viene riportato come zero e la risposta include un campo note che ne spiega il motivo.

Ruota la chiave #

Genera una nuova chiave API e invalida la precedente nello stesso passaggio. Utilizza questa funzione se sospetti che la tua chiave sia stata compromessa o come parte di una politica regolare di rotazione delle credenziali.

POST /api-keys/rotate

La nuova chiave viene mostrata una sola volta. Viene restituita in questa risposta e non può essere recuperata per intero in seguito: conservala in modo sicuro non appena la ricevi. La chiave precedente smette di funzionare nel momento in cui questa chiamata ha successo, quindi aggiorna ogni integrazione che la utilizzava.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Risposta

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

Revoca la chiave #

Elimina definitivamente la chiave API del tuo account. La revoca è immediata: ogni richiesta successiva che utilizza la chiave revocata — incluse integrazioni come Make, Zapier o script personalizzati — viene rifiutata con un 401. Per ripristinare l’accesso API in seguito, genera una nuova chiave dalle impostazioni del tuo account mentre sei connesso all’app.

DELETE /api-keys/current

Non è possibile annullare l’operazione. A differenza della rotazione, la revoca non fornisce una chiave sostitutiva. Revoca la chiave solo quando intendi interrompere l’accesso API (ad esempio, una chiave compromessa che non puoi sostituire immediatamente).

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Se l’account non ha alcuna chiave da revocare, la risposta è 404.

Chiavi con ambito limitato #

Una chiave con ambito limitato è una chiave API aggiuntiva che crei per un compito specifico, dotata solo dell’accesso necessario per tale attività. Il caso classico: vuoi collegare una dashboard client, uno strumento di reportistica o uno script interno al tuo account senza dover fornire una chiave che possa anche inviare messaggi, modificare i tuoi agenti IA o acquistare un numero di telefono.

La restrizione accompagna la chiave stessa, quindi chiunque la possieda può fare solo ciò che hai consentito al momento della creazione.

Cosa puoi limitare

Puoi anche assegnare a una chiave una data di expires_at (ISO 8601, e deve essere nel futuro). Dopo quel momento, la chiave smette di funzionare autonomamente. Se non la specifichi, la chiave non scadrà mai finché non la revocherai.

I rifiuti sono predefiniti. Se una richiesta non rientra in ciò che la chiave consente, viene rifiutata invece di essere autorizzata: una scrittura con una chiave di sola lettura restituisce 403 con error_code: "key_read_only", e qualsiasi operazione al di fuori delle sezioni consentite dalla chiave restituisce 403 con error_code: "key_scope_denied". Se una chiave con ambito limitato riceve un 403 imprevisto, l’endpoint che hai chiamato semplicemente non rientra nei suoi ambiti: amplia la chiave o usa la tua chiave principale.

Solo il proprietario dell’account gestisce le chiavi. Questi quattro endpoint richiedono la tua chiave principale o una sessione proprietario nell’app. Una chiave con ambito limitato non può mai elencare, creare, modificare o revocare chiavi, inclusa se stessa; pertanto, una chiave limitata non può mai essere utilizzata per crearne una più ampia. Il tentativo restituisce 403 con error_code: "key_scope_denied". Per lo stesso motivo, API Keys non è una sezione che puoi concedere: richiederla restituisce 400 con error_code: "invalid_scopes".

Elenca chiavi con ambito limitato #

Restituisce le chiavi con ambito limitato dell’account, dalla più recente alla meno recente (fino a 200), incluse quelle revocate, così puoi vedere cosa è stato ritirato e quando. Vengono restituite solo anteprime mascherate: il valore di una chiave con ambito limitato viene mostrato una sola volta, al momento della creazione, e non è più recuperabile in seguito.

GET /api-keys

cURL

curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

Crea una chiave con ambito limitato #

Crea una nuova chiave con ambito e ne restituisce il valore una sola volta.

POST /api-keys

La chiave viene mostrata una sola volta. È presente in questa risposta e in nessun altro posto, mai: non c’è modo di recuperarla in seguito. Salvala nel momento in cui la ricevi. Se la perdi, revocala e creane un’altra.

Campi del corpo — tutti facoltativi:

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Risposta — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

Alcuni dettagli utili da conoscere quando si sviluppa con questo metodo:

• Omettere scopes non è la stessa cosa che inviare un elenco tags vuoto. Se lasci scopes fuori del tutto, otterrai l’impostazione predefinita sicura (sola lettura, solo Analytics). Se invii "tags": [] intenzionalmente, la chiave potrà utilizzare ogni sezione: questo viene interpretato come una richiesta deliberata di una chiave senza restrizioni.
• read_only rimane true a meno che non si invii esplicitamente false. Un errore di battitura o un flag mancante non potranno mai produrre accidentalmente una chiave con permessi di scrittura.

Aggiornare una chiave con ambito #

Modifica l’etichetta, gli ambiti e/o la scadenza di una chiave. Invia una combinazione qualsiasi dei tre; inviarne nessuno restituisce 400.

PATCH /api-keys/{id}

L’{id} è l’id della chiave dall’elenco (il valore key_...), mai la chiave stessa.

Gli ambiti vengono sostituiti, non uniti. Qualsiasi cosa tu invii diventa il set completo di autorizzazioni della chiave. Questo è intenzionale: restringere una chiave non può mai lasciare silenziosamente in vigore il vecchio accesso più ampio. Invia sempre l’intero oggetto scopes che desideri, non solo il campo che stai modificando.

Il valore della chiave non cambia mai. Non esiste una rotazione sul posto per una chiave con ambito: per sostituirla, crea una nuova chiave e revoca quella vecchia, in modo che l’accesso di una credenziale non possa mai cambiare mentre è utilizzata da un’integrazione.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

Risposta

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

Se non esiste alcuna chiave con quell’id sul tuo account, la risposta è 404.

Revoca di una chiave con ambito #

La revoca è immediata: la richiesta successiva che utilizza quella chiave viene rifiutata con un 401. La tua chiave principale e ogni altra chiave con ambito non vengono influenzate.

DELETE /api-keys/{id}

La chiave rimane nel tuo elenco contrassegnata come "revoked": true, così mantieni traccia di ciò che esisteva e a cosa poteva accedere. La revoca di una chiave già revocata viene completata con successo senza modificare nulla.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Errori dell’API delle chiavi API #

Gli endpoint delle chiavi API restituiscono il formato di errore standard:

{
  "success": false,
  "error": "No API key found for this account"
}

Su un endpoint delle chiavi API, una chiave mancante o non valida restituisce 401 e un account senza una chiave registrata restituisce 404. I codici condivisi che ogni endpoint può restituire — 400, 403 (il tuo piano non include l’accesso all’API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e paginazione.

Gli endpoint delle chiavi con ambito aggiungono alcuni codici denominati nel campo error_code in modo da poter distinguere i casi:

Passaggi successivi #

• Autenticazione — i quattro modi per autenticare una richiesta e come vengono applicati gli ambiti delle chiavi.
• Errori e limiti di frequenza — codici di stato e il limite di 300 richieste/min.