Toda requisição à API e ao servidor MCP precisa de uma chave de API. Uma chave pertence a um workspace, age como o proprietário ou admin que a criou e só alcança os endpoints que os escopos dela permitem. As chaves têm o formato gr_live_ seguido de 43 letras, dígitos, hifens e sublinhados.
Criar uma chave
- 1
Abra API e agentes
No Gradiently, vá em Configurações › API e agentes e escolha o workspace da chave. Só proprietários e admins desse workspace podem criar chaves.
- 2
Dê um nome
Em Criar uma chave, preencha o Nome com o lugar onde você vai usá-la, como Claude Code ou Exportação noturna, para saber depois qual revogar.
- 3
Escolha o que ela pode fazer
Em O que ela pode fazer, selecione as permissões de que ela precisa, pelo menos uma. A próxima seção explica cada uma.
- 4
Copie uma única vez
Selecione Criar chave. A chave aparece em Copie sua chave agora, e esta é a única vez que ela é exibida. Copie para um gerenciador de senhas ou para o seu cofre de segredos e depois selecione Já salvei.
Quem criou a chave recebe um e-mail quando ela é criada e quando é revogada, com o nome, o início da chave e as permissões dela. A lista em Configurações mostra, para cada chave ativa, o nome, o início da chave, quando foi usada pela última vez e quantas permissões ela tem.
Escopos
Um escopo é uma permissão. Uma requisição precisa de todos os escopos que o endpoint dela lista, e cada ferramenta MCP precisa dos escopos de todas as requisições que faz. Conceda só o que a tarefa exige.
| Escopo | Em Configurações | O que permite |
|---|---|---|
designs:read | Ler designs | Ler marcas, designs, miniaturas e uploads, renderizar designs e acompanhar conjuntos do Designer. |
designs:write | Criar e editar designs | Criar, alterar, duplicar, compartilhar e excluir designs, enviar e excluir imagens e usar o Designer. |
marks:read | Buscar Marks | Buscar no Mercado, ler Marks e seus rascunhos, montar e revisar receitas e ler as versões dos Marks. |
marks:claim | Reservar Marks | Reservar um Mark disponível, ou um que outro dono colocou à venda, para quem criou a chave. |
brand:generate | Gerar marcas | Gerar e adotar marcas, salvar e alterar Marks em rascunho e gerenciar versões de Marks. |
workspaces:read | Ler o espaço de trabalho | Ler o workspace, os membros e o registro de auditoria. Com designs:read, ler /api/me. |
personalities:write | Editar marcas | Criar, renomear e excluir marcas, e alterar o Mark, o perfil e o estilo de uma marca. |
members:write | Convidar membros | Enviar convites para entrar no workspace. |
Chaves novas começam com Ler designs, Criar e editar designs, Buscar Marks e Gerar marcas selecionados. Reservar Marks fica desativado até você escolher, porque uma reserva torna você, quem criou a chave, o titular de um Mark.
Trocar uma chave
As chaves não expiram, e o nome e os escopos de uma chave não podem ser alterados depois que ela é criada. Para trocar uma chave, ou mudar o que ela pode fazer, substitua-a:
- 1
Crie a nova chave
Crie uma chave com os escopos que você quer, com um nome que a diferencie da antiga.
- 2
Mude suas ferramentas
Coloque a nova chave em todos os lugares que usavam a antiga: seu cliente MCP, seu cofre de segredos ou as configurações de deploy.
- 3
Revogue a chave antiga
Quando a data de usada em da chave antiga parar de mudar na lista, revogue-a.
Revogar uma chave
Em Configurações › API e agentes, selecione Revogar ao lado da chave e confirme com Revogar chave. Tudo o que a usa para de funcionar imediatamente, e isso não pode ser desfeito. Proprietários e admins do workspace podem revogar qualquer chave dele.
Uma chave também para de funcionar sozinha quando quem a criou sai do workspace, perde a função de admin ou tem a conta desativada. As chaves que uma pessoa criou são revogadas quando ela é removida do workspace ou rebaixada.
O que uma chave nunca pode fazer
Algumas coisas sempre exigem uma pessoa com login feito no Gradiently, sejam quais forem os escopos da chave:
- Criar, listar ou revogar chaves.
- Alterar a conta: perfil, e-mail, senha, sessões de login ou a exclusão da conta.
- Acessar a cobrança: planos, checkout, pagamentos, recargas de créditos de IA, Saldo e repasses. Uma reserva ou compra que exige pagamento para e pede o checkout no Gradiently.
- Abrir mão de um Mark: transferi-lo para outra pessoa, liberá-lo, colocá-lo à venda, renová-lo ou publicá-lo.
- Passar a titularidade ou a licença de um Mark para o workspace. Os Marks que uma chave reserva ficam com quem a criou, e qualquer licença continua sendo dessa pessoa.
- Mudar quem está no workspace ou as funções das pessoas, ou renomear, transferir ou excluir o workspace. Com
members:write, ela só pode enviar convites. - Alcançar qualquer workspace além do seu, mesmo um do qual quem a criou faça parte.
- Usar a administração do Gradiently.
Mantenha as chaves seguras
Faça
- Crie uma chave para cada ferramenta ou assistente, com o nome dele.
- Conceda o menor número de escopos que resolve a tarefa.
- Guarde as chaves em um gerenciador de senhas, um cofre de segredos ou uma variável de ambiente.
- Revogue uma chave assim que ela puder ter vazado e crie outra.
- Confira de vez em quando as datas de último uso e revogue as chaves que ninguém usa.
Não faça
- Fazer commit de uma chave em um repositório ou colá-la em um arquivo de configuração compartilhado.
- Colocar uma chave em uma página web, um app de celular ou qualquer coisa que rode no dispositivo de outra pessoa.
- Compartilhar uma chave entre pessoas ou ferramentas.
- Enviar uma chave por e-mail ou chat.
- Deixar Reservar Marks ativado em uma chave que não faz reservas.
O Gradiently guarda só um hash de cada chave e o início dela para exibição, então uma chave perdida não pode ser mostrada de novo: revogue-a e crie outra. Se você acha que uma chave foi mal usada, revogue-a e avise a gente.
