Env-secrets

Um env-secret é um segredo da organização (uma chave de API de terceiro, um certificado, um token) que o Imaginne injeta em uma skill no momento da execução, como variável de ambiente. Os segredos são da organização, escritos uma vez (write-only) e nunca devolvidos ao cliente. Você os gerencia em /org/env-secrets. Para o lado da skill (como declarar o que ela precisa), veja Env-secrets nas skills.

Como funciona

O segredo só é injetado se a skill o declarar em required_env. Sem carry-over entre skills.

A ideia central: o segredo só entra na skill que o declara. No acionamento, o Imaginne resolve apenas os nomes declarados pela skill (em required_env / env.secrets), filtra para o que ela realmente exige e injeta no processo daquela skill. Não há carry-over entre skills — cada uma recebe só o que declarou.

Regra de nome

O nome de um env-secret segue um padrão fixo e é único por organização:

^[A-Z][A-Z0-9_]{0,127}$

Ou seja: começa com letra maiúscula, depois letras maiúsculas, dígitos e _, até 128 caracteres. Exemplos válidos: STRIPE_API_KEY, INTERNAL_CA_PEM, SAP_TOKEN.

Tipos (kind)

Ao criar, escolha o kind, que indica a natureza do valor:

Kind	Para
string	Tokens e chaves simples.
pem	Certificados/chaves no formato PEM (multilinha).
json	Credenciais estruturadas em JSON.

Criar, rotacionar e excluir

Ação	Efeito
Criar	Nome (conforme a regra), kind e valor. O valor é write-only.
Rotate	Substitui o valor (o novo também é write-only).
Delete	Remove o segredo — com uma trava (veja abaixo).

O valor é write-only

Depois de salvo, o valor não é exibido. A ação Copy name copia apenas o nome do segredo (para usar na declaração da skill), nunca o valor. Para trocar o conteúdo, use Rotate.

Trava de exclusão

Excluir um segredo que está em uso é recusado:

• Se o env-secret está referenciado por alguma skill, o Delete retorna 422 e não apaga.
• Para forçar mesmo assim, repita com force=true — assumindo que as skills que dependem dele podem ficar sem o segredo (e falharão com missing_required_env).

Manage skills

Em Manage skills você anexa e desanexa o segredo das skills da organização. Lembre da regra de injeção:

Anexar não basta — a skill precisa declarar

O Imaginne só injeta o segredo se a skill o declarar em required_env (ou env.secrets). Anexar pelo console disponibiliza o segredo; a declaração na skill é o que faz o Imaginne entregá-lo no acionamento. Se faltar o segredo que a skill exige, a execução falha com missing_required_env — configure/anexe o env-secret correspondente.

Veja também

🧩Env-secrets nas skills

Como a skill declara o que precisa receber.

Abrir →🧠Skills (governança)

Gerenciar os segredos de uma skill pelo editor.

Abrir →🔐Credenciais

O modelo de credenciais write-only e a trava de exclusão.

Abrir →