Guida introduttiva

Segui la Guida all’Autenticazione per accedere, therefore apri la pagina Chiavi di gestione e crea una chiave di gestione. Conservala separatamente dalle chiavi dell’applicazione standard. Inviala come token bearer solo agli endpoint di Gestione della Piattaforma.

Una chiave API standard non può chiamare gli endpoint di gestione di chiavi o guardrail. Una chiave di gestione valida può comunque ricevere 403 Forbidden quando il suo proprietario non dispone più del ruolo account richiesto.

Usa GET /api/v1/keys per esaminare le chiavi visibili all’account della chiave di gestione:

Usa gli identificatori pubblici restituiti per successive richieste di recupero, aggiornamento, revoca o assegnazione di guardrail. Non dedurre mai l’accesso dal nome di una chiave o da un token mascherato.

Crea una chiave applicativa con POST /api/v1/keys. Il secret completo viene restituito solo nella risposta di creazione, quindi salvalo nel tuo gestore di secret prima di scartare quella risposta. La rotazione deve creare una sostituzione, distribuirla nell’applicazione, verificare il traffico e quindi revocare la vecchia chiave.

credit_limit_windows accetta qualsiasi combinazione di limiti di spesa progressivi 1h, 1d e 7d. Se una finestra temporale configurata viene esaurita, le chiamate con quella chiave restituiscono 429 Too Many Requests fino a quando l’utilizzo non esce dalla finestra temporale. Invia un oggetto vuoto quando aggiorni una chiave per eliminare tutti i limiti di spesa progressivi.

Quando una richiesta di creazione omette tutti i campi dei limiti di spesa e guardrail_id, la nuova chiave usa le impostazioni di governance predefinite dell’area di lavoro. Limiti espliciti, finestre mobili o un guardrail sostituiscono questa scelta predefinita. Invia credit_limit_cents: null per creare un limite nativo illimitato. Un importo specificato senza intervallo di azzeramento rimane un limite a vita. Gli aggiornamenti non riapplicano mai le impostazioni predefinite dell’area di lavoro e modificarle non cambia le chiavi esistenti.

Creazione e aggiornamento accettano tags, un array di stringhe key:value complete. Le risposte di elenco, recupero, creazione e aggiornamento restituiscono l’array completo. PATCH sostituisce l’array; omettere tags lo conserva. La chiave deve avere 1–32 caratteri e il valore 1–64, con esattamente un segno di due punti e nessuno spazio bianco. Sono consentiti al massimo 20 tag distinti, inclusi quelli predefiniti. Formati non validi o valori predefiniti in conflitto restituiscono 422 con errori di validazione; un valore diverso da un array o un elemento non stringa restituisce 400.

È richiesto esattamente un tag di scopo: usage:developer o usage:service. La creazione tramite Management API aggiunge usage:service se non viene indicato uno scopo, anche con tags: []. La creazione nel Dashboard e gli aggiornamenti senza scopo usano usage:developer. Le chiavi esistenti vengono migrate come Developer. L’ambiente è facoltativo e accetta al massimo uno fra env:production, env:staging o env:dev (env:prod non è accettato).

La dashboard offre scorciatoie per scopo e ambiente durante la creazione e la modifica, oltre a tag personalizzati e suggerimenti dalle sole chiavi standard conservate nello spazio di lavoro corrente. Gli elenchi mostrano i valori e il tag completo al passaggio del mouse. I tag non modificano proprietà, visibilità o autorizzazioni delle chiavi. Possono associare una chiave a un budget condiviso per tag.

Gli amministratori dello spazio di lavoro impostano i tag obbligatori di un membro in Team, tramite il modulo del budget del membro. Sono tag personalizzati che distinguono maiuscole e minuscole, come team:growth. Gli spazi dei nomi usage: e env: sono riservati. Un membro può avere al massimo 19 tag obbligatori e ogni chiave resta limitata a 20 tag totali.

Ogni nuova chiave standard include automaticamente i tag obbligatori del proprietario nello spazio di lavoro. La creazione combina i tag inviati con quelli obbligatori prima della convalida. Ad esempio, se il membro richiede team:growth, una richiesta di creazione della Management API con tags: ["project:chatbot"] restituisce project:chatbot, team:growth e il valore predefinito usage:service.

Un PATCH che fornisce tags deve conservare tutti i tag obbligatori. Rimuoverne uno restituisce 422 con un errore di convalida che indica i tag mancanti, anche quando il chiamante è un amministratore. Omettere tags conserva i tag della chiave. I membri possono comunque aggiungere o rimuovere tag ordinari.

Per rimuovere un tag obbligatorio, un amministratore modifica la configurazione del membro in Team. Il salvataggio aggiunge i nuovi tag obbligatori a tutte le chiavi standard esistenti del membro e rimuove quelli revocati. Gli altri tag restano invariati. Sono incluse le chiavi disabilitate e scadute, ma escluse quelle eliminate. Se una chiave non può accettare l’insieme finale di tag, l’intero salvataggio non riesce e il modulo indica la chiave da correggere.

I budget per tag usano i tag correnti di ogni chiave. Modificare i tag obbligatori cambia anche l’attribuzione al budget della spesa esistente nel periodo corrente. Aggiungere un tag obbligatorio può esaurirne immediatamente il budget. I membri esistenti iniziano senza tag obbligatori e le loro chiavi restano invariate finché un amministratore non salva una configurazione.

I Guardrail sono policy di account riutilizzabili per i controlli su modello, provider e spesa. Gestisci le policy tramite /api/v1/guardrails, quindi utilizza /api/v1/guardrail_assignments per associarle o rimuoverle. Considera un’assegnazione rifiutata come un errore di policy o di proprietà anziché continuare silenziosamente senza il guardrail.

Crea una protezione positiva in modalità block, poi assegna il suo guardrail_id e un tag sensibile alle maiuscole come dept:ml. Scegli una sola destinazione, api_token_id, account_user_id o tag. I budget per tag richiedono un amministratore. Quelli disattivati non applicano limiti. Le richieste di gestione non consumano budget.

I budget aggregano i tag attuali delle chiavi standard, incluse le spese delle chiavi eliminate, disattivate e scadute. Aggiungere o rimuovere un tag sposta le spese della chiave nel periodo attuale. Creare o ricreare un budget non azzera mai le spese. Il conteggio esclude le chiavi eliminate. Ogni budget corrispondente deve autorizzare la richiesta; il rifiuto restituisce 403 e il nome del tag.

Un credit_limit_reset_interval nullo indica un limite permanente. Gli altri periodi usano UTC. La soglia di avviso predefinita è 80 e accetta da 1 a 100. Le modifiche dirette interessano tutte le assegnazioni; il pannello copia prima la politica quando modifica un budget per tag.

L’ammissione controlla le prenotazioni. Il saldo effettivo può superarle, mostrare un utilizzo oltre il 100% e bloccare le successive richieste a pagamento. I registri usano la propria data di creazione; le attività in attesa e i batch usano la loro. Un’attività accettata in un periodo può essere contabilizzata in uno successivo.