Cada pedido à API e ao servidor MCP precisa de uma chave de API. Uma chave pertence a um espaço de trabalho, atua como o proprietário ou admin que a criou e só chega aos endpoints que os seus âmbitos permitem. As chaves têm o formato gr_live_ seguido de 43 letras, algarismos, hífenes e sublinhados.
Criar uma chave
- 1
Abre API e agentes
No Gradiently, vai a Definições › API e agentes e escolhe o espaço de trabalho a que a chave se destina. Só os proprietários e admins desse espaço de trabalho podem criar chaves.
- 2
Dá-lhe um nome
Em Criar uma chave, dá-lhe um Nome conforme o sítio onde a vais usar, como Claude Code ou Exportação noturna, para saberes qual revogar mais tarde.
- 3
Escolhe o que pode fazer
Em O que pode fazer, seleciona as permissões de que precisa, pelo menos uma. A secção seguinte explica cada uma.
- 4
Copia-a uma vez
Seleciona Criar chave. A chave aparece em Copia a tua chave agora, e é a única vez que é mostrada. Copia-a para um gestor de palavras-passe ou para o teu cofre de segredos, e depois seleciona Já guardei.
Quem criou uma chave recebe um email quando ela é criada e quando é revogada, com o seu nome, o início da chave e as suas permissões. A lista nas Definições mostra, para cada chave ativa, o nome, o início da chave, quando foi usada pela última vez e quantas permissões tem.
Âmbitos
Um âmbito é uma permissão. Um pedido precisa de todos os âmbitos que o seu endpoint indica, e cada ferramenta MCP precisa dos âmbitos de todos os pedidos que faz. Concede só o que a tarefa exige.
| Âmbito | Nas Definições | O que permite |
|---|---|---|
designs:read | Ler designs | Ler marcas, designs, miniaturas e carregamentos, gerar designs e acompanhar conjuntos do Designer. |
designs:write | Criar e editar designs | Criar, alterar, duplicar, partilhar e eliminar designs, carregar e eliminar imagens, e executar o Designer. |
marks:read | Pesquisar Marks | Pesquisar o Mercado, ler Marks e os teus rascunhos, construir e rever receitas, e ler versões de Marks. |
marks:claim | Reservar Marks | Reservar um Mark disponível, ou um que outro detentor pôs à venda, para o criador da chave. |
brand:generate | Gerar marcas | Gerar e adotar marcas, guardar e alterar Marks em rascunho, e gerir versões de Marks. |
workspaces:read | Ler o espaço de trabalho | Ler o espaço de trabalho, os seus membros e o registo de auditoria. Com designs:read, ler /api/me. |
personalities:write | Editar marcas | Criar, renomear e eliminar marcas, e alterar o Mark, o perfil e o estilo de uma marca. |
members:write | Convidar membros | Enviar convites para entrar no espaço de trabalho. |
As novas chaves começam com Ler designs, Criar e editar designs, Pesquisar Marks e Gerar marcas selecionados. Reservar Marks fica desligado até o escolheres, porque uma reserva torna-te a ti, criador da chave, detentor de um Mark.
Rodar uma chave
As chaves não expiram, e o nome e os âmbitos de uma chave não podem ser alterados depois de criada. Para rodar uma chave, ou para mudar o que pode fazer, substitui-a:
- 1
Cria a nova chave
Cria uma chave com os âmbitos que queres, com um nome que a distinga da antiga.
- 2
Muda as tuas ferramentas
Põe a nova chave em todos os sítios que usavam a antiga: o teu cliente MCP, o cofre de segredos ou as definições de implementação.
- 3
Revoga a chave antiga
Quando a data usada a da chave antiga deixar de mudar na lista, revoga-a.
Revogar uma chave
Em Definições › API e agentes, seleciona Revogar ao lado da chave e confirma com Revogar chave. Tudo o que a usa deixa de funcionar de imediato, e não é possível anular. Os proprietários e admins do espaço de trabalho podem revogar qualquer uma das suas chaves.
Uma chave também deixa de funcionar sozinha quando o seu criador sai do espaço de trabalho, é despromovido abaixo de admin ou tem a conta desativada. As chaves que uma pessoa criou são revogadas quando ela é removida do espaço de trabalho ou despromovida.
O que uma chave nunca pode fazer
Algumas coisas precisam sempre de uma pessoa com sessão iniciada no Gradiently, sejam quais forem os âmbitos da chave:
- Criar, listar ou revogar chaves.
- Alterar a conta: perfil, email, palavra-passe, sessões iniciadas, ou eliminá-la.
- Aceder à faturação: planos, checkout, pagamentos, recargas de créditos de IA, Saldo e transferências. Uma reserva ou compra que exija pagamento para e pede o checkout no Gradiently.
- Dar um Mark a outra pessoa: transferi-lo, libertá-lo, pô-lo à venda, renová-lo ou publicá-lo.
- Passar a detenção ou a licença de um Mark para o espaço de trabalho. Os Marks que uma chave reserva ficam com o seu criador, e qualquer licença continua a ser dele.
- Alterar quem está no espaço de trabalho ou as suas funções, renomear, transferir ou eliminar o espaço de trabalho. Com
members:writesó pode enviar convites. - Aceder a outro espaço de trabalho que não o seu, mesmo que o seu criador pertença a ele.
- Usar a administração do Gradiently.
Manter as chaves seguras
Faz
- Cria uma chave para cada ferramenta ou assistente, com o nome dele.
- Concede o menor número de âmbitos que faça o trabalho.
- Guarda as chaves num gestor de palavras-passe, num cofre de segredos ou numa variável de ambiente.
- Revoga uma chave assim que possa ter sido exposta, e depois cria uma nova.
- Verifica de vez em quando as datas de última utilização, e revoga as chaves que ninguém usa.
Não faças
- Fazer commit de uma chave num repositório ou colá-la num ficheiro de configuração partilhado.
- Pôr uma chave numa página web, numa app móvel ou em qualquer coisa que corra no dispositivo de outra pessoa.
- Partilhar uma chave entre pessoas ou ferramentas.
- Enviar uma chave por email ou chat.
- Deixar Reservar Marks ligado numa chave que não reserva.
O Gradiently guarda só um hash de cada chave e o seu início para mostrar, por isso uma chave perdida não pode voltar a ser mostrada: revoga-a e cria outra. Se achares que uma chave foi mal usada, revoga-a e avisa-nos.
