Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Gerar e Proteger a Sua Chave de API

Aula 2 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. A credencial que autentica os seus pedidos
  2. Gerar a sua primeira chave
  3. Armazená-la sem nunca a codificar diretamente
  4. Rotacionar as suas chaves
  5. Reduzir a superfície de exposição
  6. Pontos-chave

A credencial que autentica os seus pedidos

A sua chave de API autentica todos os pedidos enviados aos modelos da Mistral: sem ela, nenhuma chamada é aceite. Encare-a como uma palavra-passe técnica, exceto que viaja através de código, ficheiros de configuração e pipelines de implementação, o que significa que acaba em muito mais locais do que uma palavra-passe padrão. Qualquer pessoa que a possua pode consumir a sua quota e gerar custos na sua conta.

Gerar a sua primeira chave

Na Consola da Mistral, abra o seu espaço de trabalho e navegue até à secção API Keys na barra lateral. Clique em Create new key e atribua-lhe um nome descritivo, como dev-chatbot-mars-2026. Este nome não tem função técnica, mas salvar-lhe-á o dia quando seis chaves coexistirem na lista e precisar de revogar apenas uma: “chave 3” não lhe diz nada, enquanto dev-chatbot-mars-2026 diz-lhe tudo.

A chave é apresentada apenas uma vez, no momento da criação. Copie-a imediatamente e guarde-a num local seguro. Se fechar a janela antes de a copiar, não há forma de a recuperar: terá de gerar uma nova. Uma chave da Mistral consiste num prefixo seguido de uma longa cadeia alfanumérica. Não a confunda com o ID do seu espaço de trabalho ou com um token JWT: ao contrário deste último, não expira por si só e permanece válida até que a revogue.

Armazená-la sem nunca a codificar diretamente

A regra de ouro é simples: nunca codifique diretamente a sua chave de API no código-fonte. No dia em que esse ficheiro acabar num repositório partilhado, a chave vai com ele. Utilize sempre uma variável de ambiente.

No Linux e macOS, declare-a no terminal:

export MISTRAL_API_KEY="your-api-key-here"

Esta variável desaparece quando fecha o terminal; para a tornar persistente, adicione a linha ao seu ficheiro ~/.bashrc, ~/.zshrc ou ~/.profile.

No Windows, o equivalente em PowerShell é o seguinte:

$env:MISTRAL_API_KEY = "your-api-key-here"

E para sobreviver a um reinício da sessão:

[System.Environment]::SetEnvironmentVariable("MISTRAL_API_KEY", "your-api-key-here", "User")

Num projeto de aplicação, a prática mais comum é criar um ficheiro .env na raiz:

MISTRAL_API_KEY=your-api-key-here

Adicione .env ao seu .gitignore imediatamente — antes do seu primeiro commit, não depois. Em Python, a biblioteca python-dotenv lê este ficheiro e injeta as variáveis no arranque, oferecendo-lhe a conveniência de um ficheiro local sem o risco de versionar segredos.

Rotacionar as suas chaves

Substitua uma chave por três razões. Imediatamente, se tiver sido exposta de alguma forma: um commit enviado para um repositório Git público, uma mensagem apressada no Slack ou vestígios nos registos do servidor. Regularmente em produção, sendo noventa dias uma cadência razoável. E quando um colaborador sai que tinha acesso, no mesmo dia em que devolve o crachá.

O procedimento evita interrupções de serviço se respeitar a ordem:

  1. Gere uma nova chave na Consola
  2. Atualize a variável de ambiente em todas as suas implementações
  3. Verifique se tudo funciona com a nova chave
  4. Revogue a chave antiga apenas após esta verificação

Trocar os passos 3 e 4 é o erro clássico: revoga primeiro “para estar seguro”, apenas para descobrir que um serviço esquecido ainda estava a usar a chave antiga. Esta rotação sem tempo de inatividade garante que nenhum componente falha durante a transição.

Reduzir a superfície de exposição

Se várias aplicações chamarem a API, crie uma chave por aplicação. Se uma for comprometida, só precisa de revogar essa chave específica sem parar as outras. Pelo mesmo princípio, nunca reutilize uma chave de produção em desenvolvimento: é precisamente nesse ambiente que os segredos circulam mais livremente.

De seguida, monitore a utilização a partir da Consola, que expõe registos de utilização para cada chave. Um pico súbito de tokens ou chamadas a partir de um endereço IP desconhecido deve desencadear uma rotação imediata, sem esperar pela confirmação do incidente.

Três erros finais merecem menção porque os encontramos todas as semanas. Uma chave publicada num repositório Git público permanece legível no histórico mesmo após o ficheiro ser eliminado: a única resposta válida é a revogação. Uma chave enviada em texto simples por e-mail ou mensageiro instantâneo fica arquivada para sempre em servidores que não controla. E uma chave expirada ou revogada que permaneça numa implementação produz erros 401 Unauthorized que muitas vezes levam uma hora a diagnosticar, simplesmente porque ninguém pensou em verificar.

Pontos-chave

  • Gere as suas chaves a partir da secção API Keys do seu espaço de trabalho na Consola da Mistral
  • Armazene-as exclusivamente em variáveis de ambiente ou num gestor de segredos
  • Efetue uma rotação regular e uma rotação imediata em caso de exposição
  • Crie uma chave por aplicação para limitar o impacto de um comprometimento
  • Sempre adicione .env ao seu .gitignore