Autenticazione e chiavi API
Come inviare la tua chiave API, quante chiavi puoi avere, cosa può e non può fare una chiave, cosa fare quando una finisce nelle mani sbagliate, e come scollegare un assistente IA.
Invia la chiave nell'intestazione Authorization
Authorization: Bearer YOUR_API_KEYL'API legge una chiave solo lì.
- Non mettere mai una chiave in un URL (
?api_key=…). Gli URL finiscono nei log, nella cronologia del browser e nei link condivisi. L'API rifiuta una richiesta del genere con400 api_key_in_query. Considera quella chiave esposta: revocala e creane una nuova. - Chiama
https://author.trueroyalties.com/api/v1. Lo stesso percorso sutrueroyalties.comrisponde404 wrong_host. Non facciamo mai redirect: un client che segue un redirect verso un altro indirizzo perde la tua chiave per strada. - Chiama l'API da un foglio di calcolo, uno script o un server, non dal codice di una pagina web: qualsiasi visitatore della pagina potrebbe leggere la chiave.
Cosa può fare una chiave
- Leggere tutti i numeri del tuo account, su tutti gli endpoint.
- Non modificare nulla. L'API è in sola lettura.
- Condividere i limiti del tuo account: tutte le tue chiavi e gli assistenti IA collegati contano insieme, quindi una seconda chiave non ti dà più richieste. Vedi Limiti ed errori.
Creare una chiave
Impostazioni → API → Crea una chiave.
- Il nome ha al massimo 40 caratteri. Usa il nome dello strumento, così saprai poi quale chiave revocare.
- La chiave viene mostrata una sola volta. Ne conserviamo solo un'impronta: nessuno può mostrarla di nuovo, nemmeno noi. Tienila in un gestore di password o nelle impostazioni segrete del tuo strumento.
- Puoi avere 10 chiavi alla volta.
- L'account demo pubblico non può creare chiavi.
L'elenco delle chiavi
Ogni chiave mostra il nome, i primi caratteri (tr_live_ab12…), quando è stata
creata e quando è stata usata l'ultima volta.
«Ultimo utilizzo» si aggiorna al massimo una volta all'ora: una chiave usata pochi minuti fa può ancora mostrare un'ora precedente.
Revocare una chiave
Apri il menu ⋯ della chiave e scegli Revoca.
L'effetto è immediato: la richiesta successiva con quella chiave riceve
401 unauthorized, la stessa risposta di una chiave mai esistita. Una chiave
revocata non si recupera: creane una nuova.
Assistenti IA collegati senza chiave
claude.ai e ChatGPT non usano una chiave: accedi a TrueRoyalties dall'assistente e fai clic su Consenti. L'assistente riceve così un accesso tutto suo, che può solo leggere. Come collegarne uno: Collega un assistente IA.
- Impostazioni → API → App collegate elenca ogni assistente, l'indirizzo che ha chiesto l'accesso, quando l'hai collegato e quando ha letto i tuoi numeri l'ultima volta (aggiornato al massimo una volta all'ora).
- Non verificata accanto a un nome significa che l'app si è registrata senza dimostrare il proprio indirizzo. Tienila solo se l'hai collegata tu.
- Per fermarne uno, apri il suo menu ⋯ e scegli Scollega. L'effetto è immediato. Per usarlo di nuovo, ricollegalo dall'assistente.
Quando una richiesta viene rifiutata
| Risposta | Perché | Cosa fare |
|---|---|---|
401 unauthorized | Nessuna intestazione Authorization, o una chiave sbagliata o revocata | Controlla intestazione e chiave |
403 subscription_inactive | Il tuo abbonamento è terminato | Abbonati in Impostazioni → Fatturazione |
400 api_key_in_query | La chiave era nell'URL | Spostala nell'intestazione, poi revocala |
404 wrong_host | La richiesta è andata a trueroyalties.com | Usa author.trueroyalties.com |
Tutti gli altri codici sono descritti in Limiti ed errori.
La chiave demo pubblica
Il riferimento dell'API precompila il pulsante Try it con una chiave pubblica. Legge solo l'account demo, i cui numeri sono fittizi, ed è limitata a 10 richieste al minuto, condivise tra tutti i visitatori. Non può leggere il tuo account: per quello usa la tua chiave.