Autenticação e chaves de API
Como enviar sua chave de API, quantas chaves você pode ter, o que uma chave pode e não pode fazer, o que fazer quando uma vaza, e como desconectar um assistente de IA.
Envie a chave no cabeçalho Authorization
Authorization: Bearer YOUR_API_KEYA API só lê uma chave nesse cabeçalho.
- Nunca coloque uma chave em uma URL (
?api_key=…). URLs acabam em logs, no histórico do navegador e em links compartilhados. A API recusa essa requisição com400 api_key_in_query. Considere essa chave exposta: revogue-a e crie uma nova. - Chame
https://author.trueroyalties.com/api/v1. O mesmo caminho emtrueroyalties.comresponde404 wrong_host. Nunca redirecionamos: um cliente que segue um redirecionamento para outro endereço perde sua chave no caminho. - Chame a API a partir de uma planilha, um script ou um servidor, não do código de uma página web: qualquer visitante da página poderia ler a chave.
O que uma chave pode fazer
- Ler todos os números da sua conta, em todos os endpoints.
- Não alterar nada. A API é somente leitura.
- Compartilhar os limites da sua conta: todas as suas chaves e assistentes de IA conectados contam juntos, então uma segunda chave não dá mais requisições. Veja Limites e erros.
Criar uma chave
Configurações → API → Criar uma chave.
- O nome tem no máximo 40 caracteres. Use o nome da ferramenta, para saber depois qual chave revogar.
- A chave é mostrada uma única vez. Guardamos só uma impressão digital dela: ninguém pode mostrá-la de novo, nem nós. Guarde-a em um gerenciador de senhas ou nas configurações secretas da sua ferramenta.
- Você pode ter 10 chaves ao mesmo tempo.
- A conta de demonstração pública não pode criar chaves.
A lista de chaves
Cada chave mostra o nome, os primeiros caracteres (tr_live_ab12…), quando foi
criada e quando foi usada pela última vez.
"Último uso" é atualizado no máximo uma vez por hora: uma chave usada há alguns minutos ainda pode mostrar um horário anterior.
Revogar uma chave
Abra o menu ⋯ da chave e escolha Revogar.
O efeito é imediato: a próxima requisição com essa chave recebe
401 unauthorized, a mesma resposta de uma chave que nunca existiu. Uma chave
revogada não pode ser restaurada: crie uma nova.
Assistentes de IA conectados sem chave
O claude.ai e o ChatGPT não usam chave: você entra no TrueRoyalties pelo assistente e clica em Permitir. O assistente recebe então um acesso próprio, que só pode ler. Como conectar um: Conectar um assistente de IA.
- Configurações → API → Apps conectados lista cada assistente, o endereço que pediu acesso, quando você o conectou e quando ele leu seus números pela última vez (atualizado no máximo uma vez por hora).
- Não verificado ao lado de um nome significa que o app se registrou sem provar seu endereço. Mantenha-o só se foi você quem o conectou.
- Para parar um, abra o menu ⋯ e escolha Desconectar. O efeito é imediato. Para usá-lo de novo, conecte-o outra vez pelo assistente.
Quando uma requisição é recusada
| Resposta | Por quê | O que fazer |
|---|---|---|
401 unauthorized | Sem cabeçalho Authorization, ou uma chave errada ou revogada | Confira o cabeçalho e a chave |
403 subscription_inactive | Sua assinatura terminou | Assine em Configurações → Cobrança |
400 api_key_in_query | A chave estava na URL | Passe-a para o cabeçalho e revogue-a |
404 wrong_host | A requisição foi para trueroyalties.com | Use author.trueroyalties.com |
Todos os outros códigos estão em Limites e erros.
A chave de demonstração pública
A referência da API preenche o botão Try it com uma chave pública. Ela lê só a conta de demonstração, cujos números são fictícios, e está limitada a 10 requisições por minuto, compartilhadas entre todos os visitantes. Ela não consegue ler sua conta: para isso, use sua própria chave.