Source: https://ailoot.ai/docs/it/cabinet/keys/ Canonical: https://ailoot.ai/docs/it/cabinet/keys/ Language: it [API dell’area personale](https://ailoot.ai/docs/it/) # Chiavi API [Markdown](https://ailoot.ai/docs/it/cabinet/keys/index.md) Metodi, campi delle richieste e risposte. La sezione contiene 5 metodi. Apri un metodo per vedere condizioni di accesso, campi della richiesta e risposta. | Metodo e percorso | Descrizione | Accesso | | --- | --- | --- | | `GET /api/v1/keys` | Elenco — chiavi API | Token dell’area personale | | `POST /api/v1/keys` | Creazione di una chiave API | Token dell’area personale | | `DELETE /api/v1/keys/:id` | Eliminazione — chiavi API | Token dell’area personale | | `GET /api/v1/keys/:id` | Recupero per identificatore — chiavi API | Token dell’area personale | | `PUT /api/v1/keys/:id` | Modifica di una chiave API | Token dell’area personale | **GET /api/v1/keys** — Elenco — chiavi API Accesso: token dell’area personale GET`/api/v1/keys` Lettura; l’ID si ricava dalla risposta precedente che hai ricevuto ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys" \ -H "Authorization: Bearer $TOKEN" ``` ## Parametri query | Il campo | Tipo | Obbligatorio | Verifica / descrizione | | --- | --- | --- | --- | | `sort_by` | `string` | no | ; predefinito: created\_at | | `sort_order` | `string` | no | ; predefinito: desc | | `search` | `string` | no | | | `status` | `string` | no | | | `page` | `integer` | no | ; predefinito: 1; positivo; page\_size/limit \<=1000 | | `page_size` | `integer` | no | ; predefinito: 20; positivo; page\_size/limit \<=1000 | | `limit` | `integer` | no | ; predefinito: 20; positivo; page\_size/limit \<=1000 | Il corpo della richiesta non è necessario. Passa i parametri indicati sopra nell’URL. ## Risposta La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto. Schemi dei dati della risposta: `APIKey`. Campi e tipi sono nelle pagine «Schemi dei dati». Schema della risposta, valori illustrativi ```json { "code": 0, "message": "success", "data": { "items": [ { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } ], "total": "PLACEHOLDER_TOTAL (integer)", "page": "PLACEHOLDER_PAGE (integer)", "page_size": "PLACEHOLDER_PAGE_SIZE (integer)", "pages": "PLACEHOLDER_PAGES (integer)" } } ``` Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT. Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali. **POST /api/v1/keys** — Creazione di una chiave API Accesso: token dell’area personale POST`/api/v1/keys` ## Campi JSON / modulo | Il campo | Tipo | Obbligatorio | Verifica / descrizione | | --- | --- | --- | --- | | `name` | `string` | sì | required | | `custom_key` | `string` | no | ; Valore personalizzato facoltativo della chiave; può essere null | | `ip_whitelist` | `array` | no | ; Elenco degli IP consentiti | | `ip_blacklist` | `array` | no | ; Elenco degli IP bloccati | | `quota` | `number` | no | ; Limite di spesa della chiave in USD; può essere null | | `expires_in_days` | `integer` | no | ; Durata di validità in giorni; può essere null | | `rate_limit_5h` | `number` | no | ; può essere null | | `rate_limit_1d` | `number` | no | ; può essere null | | `rate_limit_7d` | `number` | no | ; può essere null | Modello del corpo della richiesta ```json { "name": "PLACEHOLDER_NAME (string)", "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "quota": "PLACEHOLDER_QUOTA (number)", "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)" } ``` PLACEHOLDER indica il tuo input e il suo tipo. Sostituisci i valori e mantieni solo i campi facoltativi necessari; i segnaposto stringa non vanno inviati al posto di numeri, boolean, oggetti o array. Schema della richiesta: `CreateAPIKeyRequest` ## Risposta La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto. Schemi dei dati della risposta: `APIKey`. Campi e tipi sono nelle pagine «Schemi dei dati». Schema della risposta, valori illustrativi ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT. Particolarità: L’operazione modifica lo stato o prosegue un’autorizzazione monouso; l’esempio descrive il contratto e non viene eseguito. Particolarità: Idempotency-Key è supportato; un invio ripetuto restituisce la risposta salvata con X-Idempotency-Replayed. Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali. Il metodo modifica i dati. Ripetere l’invio è sicuro solo quando il metodo indica Idempotency-Key. Se la risposta va persa, controlla prima il risultato (ad esempio l’elenco delle chiavi), poi decidi se ripetere la richiesta. **DELETE /api/v1/keys/:id** — Eliminazione — chiavi API Accesso: token dell’area personale DELETE`/api/v1/keys/:id` ## Parametri del percorso | Il campo | Tipo | Obbligatorio | Verifica / descrizione | | --- | --- | --- | --- | | `id` | `integer` | sì | | Il corpo della richiesta non è necessario. ## Risposta La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto. Schema della risposta, valori illustrativi ```json { "code": 0, "message": "success", "data": { "message": "VALUE_FROM_RESPONSE" } } ``` Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT. Particolarità: L’operazione modifica lo stato o prosegue un’autorizzazione monouso; l’esempio descrive il contratto e non viene eseguito. Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali. Il metodo modifica i dati. Ripetere l’invio è sicuro solo quando il metodo indica Idempotency-Key. Se la risposta va persa, controlla prima il risultato (ad esempio l’elenco delle chiavi), poi decidi se ripetere la richiesta. **GET /api/v1/keys/:id** — Recupero per identificatore — chiavi API Accesso: token dell’area personale GET`/api/v1/keys/:id` Lettura; l’ID si ricava dalla risposta precedente che hai ricevuto ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \ -H "Authorization: Bearer $TOKEN" ``` ## Parametri del percorso | Il campo | Tipo | Obbligatorio | Verifica / descrizione | | --- | --- | --- | --- | | `id` | `integer` | sì | | Il corpo della richiesta non è necessario. Passa i parametri indicati sopra nell’URL. ## Risposta La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto. Schemi dei dati della risposta: `APIKey`. Campi e tipi sono nelle pagine «Schemi dei dati». Schema della risposta, valori illustrativi ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT. Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali. **PUT /api/v1/keys/:id** — Modifica di una chiave API Accesso: token dell’area personale PUT`/api/v1/keys/:id` ## Parametri del percorso | Il campo | Tipo | Obbligatorio | Verifica / descrizione | | --- | --- | --- | --- | | `id` | `integer` | sì | | ## Campi JSON / modulo | Il campo | Tipo | Obbligatorio | Verifica / descrizione | | --- | --- | --- | --- | | `name` | `string` | no | | | `status` | `string` | no | omitempty,oneof=active inactive | | `ip_whitelist` | `array` | no | ; IP consentiti: null non modifica l’elenco, un array vuoto lo cancella; può essere null | | `ip_blacklist` | `array` | no | ; IP bloccati: null non modifica l’elenco, un array vuoto lo cancella; può essere null | | `quota` | `number` | no | ; Limite di spesa della chiave in USD; 0 — senza limite; può essere null | | `expires_at` | `string` | no | ; Data e ora di scadenza nel formato ISO 8601; può essere null | | `reset_quota` | `boolean` | no | ; Azzera la quota consumata del limite di spesa; può essere null | | `rate_limit_5h` | `number` | no | ; può essere null | | `rate_limit_1d` | `number` | no | ; può essere null | | `rate_limit_7d` | `number` | no | ; può essere null | | `reset_rate_limit_usage` | `boolean` | no | ; Azzera la spesa conteggiata nelle finestre; può essere null | Modello del corpo della richiesta ```json { "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "quota": "PLACEHOLDER_QUOTA (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)" } ``` PLACEHOLDER indica il tuo input e il suo tipo. Sostituisci i valori e mantieni solo i campi facoltativi necessari; i segnaposto stringa non vanno inviati al posto di numeri, boolean, oggetti o array. Schema della richiesta: `UpdateAPIKeyRequest` ## Risposta La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto. Schemi dei dati della risposta: `APIKey`. Campi e tipi sono nelle pagine «Schemi dei dati». Schema della risposta, valori illustrativi ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT. Particolarità: L’operazione modifica lo stato o prosegue un’autorizzazione monouso; l’esempio descrive il contratto e non viene eseguito. Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali. Particolarità: Finché la chiave ha richieste non concluse con una riserva, non è consentito ridurre il suo limite di spesa né azzerarne il consumo registrato. Trasmetti solo i campi che modifichi. Il metodo modifica i dati. Ripetere l’invio è sicuro solo quando il metodo indica Idempotency-Key. Se la risposta va persa, controlla prima il risultato (ad esempio l’elenco delle chiavi), poi decidi se ripetere la richiesta. Hai altre domande? Invia il Request ID e una descrizione — ti aiuteremo a chiarire il problema.[Contatta l’assistenza](mailto:support@ailoot.ai) ## Ailoot · L’azienda e il suo portafoglio di progetti Ailoot si basa su un’esperienza operativa consolidata, un’ampia base di clienti, un servizio stabile e un controllo costante dei KPI. L’azienda e il suo portafoglio di progetti: milioni di clienti; vendite nell’ordine dei miliardi ogni mese. Ailoot mette questa esperienza operativa al servizio dell’accesso API alle funzioni AI nei prodotti dei clienti, negli agenti, nelle applicazioni e nelle automazioni.