Secrets

Secrets são pares chave-valor que guardam dados sensíveis, como chaves de API, tokens e senhas. Em vez de deixar valores fixos dentro dos seus workflows, você os guarda como secrets e os referencia pelo nome em tempo de execução.

Gerenciando secrets

Para gerenciar secrets, abra as Settings do seu workspace e vá até a aba Secrets.

Os secrets ficam organizados em duas seções:

• Workspace — compartilhados com todos os membros do seu workspace
• Personal — privados, só seus

Membros externos do workspace contam como membros do workspace para os secrets com escopo de workspace. Eles podem usar os secrets do workspace conforme o nível de permissão que têm nele, mesmo não sendo membros da sua organização.

Adicionando um secret

Digite o nome da chave (por exemplo, OPENAI_API_KEY) na coluna Key e o valor na coluna Value, na última linha vazia. Uma nova linha vazia aparece automaticamente conforme você digita. Os valores existentes ficam mascarados por padrão.

Quando terminar, clique em Save para gravar todas as alterações.

Importação em massa

Você pode preencher vários secrets de uma vez colando conteúdo em formato .env em qualquer campo de chave ou de valor. O parser aceita pares KEY=VALUE padrão, export KEY=VALUE, valores entre aspas e comentários inline.

Editando e excluindo

Clique direto em qualquer célula de chave ou valor para editá-la. Para excluir um secret, clique no ícone de lixeira na linha dele e salve.

Usando secrets em workflows

Para referenciar um secret em qualquer campo de entrada, digite {{ para abrir o dropdown de variáveis. Seus secrets disponíveis aparecem agrupados por escopo (primeiro workspace, depois personal).

Selecione o secret que você quer usar. A referência aparece destacada em azul e é resolvida para o valor real em tempo de execução.

Proteção nos logs de execução

Quando um secret salvo é substituído com sucesso por uma referência {{KEY}}, o Studio mascara as ocorrências exatas (sensíveis a maiúsculas e minúsculas) do valor resolvido em todo conteúdo que vai para os logs. Isso inclui a exibição ao vivo do log do block no editor, a entrada e a saída no Logs Overview, os traces de execução armazenados, as respostas da API de leitura de logs e a saída de Get Run Details do block Logs. As entradas, saídas e erros dos spans de Function e Agent, o thinking do Agent e os argumentos, resultados e erros das chamadas de ferramenta do Agent também são protegidos. A substituição normalmente aparece como {{KEY}}.

A resolução dos secrets e o comportamento funcional do workflow não mudam: blocks, ferramentas e etapas seguintes recebem o valor real de execução. Os dados funcionais de execução armazenados, as respostas de execução do workflow, os streams, os callbacks, o estado dos blocks e os snapshots não são reescritos. As visualizações e as APIs de leitura de logs recebem uma cópia protegida separada, então o Workflow Input e o Workflow Output do Logs Overview aparecem mascarados sem alterar o resultado real do workflow. As requisições ao modelo recebem outra projeção protegida: os valores exatos dos secrets conhecidos pela execução são trocados por {{KEY}} antes de qualquer mensagem, prompt, argumento de ferramenta ou continuação de ferramenta visível ao modelo sair do Studio.

Execução de código no Chat

As ferramentas Function e de execução de código do Chat só recebem um secret salvo quando o código contém explicitamente uma referência {{KEY}} válida. Acesso direto a environmentVariables.KEY, shell $KEY, nomes dinâmicos, literais e secrets configurados mas não usados não montam nenhum valor. A execução de código exige acesso de escrita ao workspace, e quem chama também precisa ter permissão para ver o valor bruto: seus próprios secrets Personal, qualquer secret em que você seja Admin de credencial e os secrets de Workspace quando você é admin do workspace. Quem é Member de credencial continua podendo usar os secrets compartilhados pela resolução normal de workflows e ferramentas, mas não pode montar o texto puro deles em código arbitrário do Chat.

As superfícies headless usam a configuração Secret access que estiver salva:

• Block Studio Chat — em Show additional fields
• Scheduled Tasks — no modal da tarefa
• Inbox — em Settings → Inbox → Secrets

Escolha All secrets ou Selected secrets. Configurações existentes assumem All secrets por compatibilidade. Mesmo All secrets significa apenas os secrets referenciados explicitamente com {{KEY}} que o ator da execução pode ver; nunca injeta o ambiente inteiro. Mensagens no Inbox vindas de remetentes externos permitidos não recebem acesso a secrets brutos.

O código recebe o valor real autorizado em tempo de execução. Antes de qualquer resultado de ferramenta visível ao Chat ser devolvido, as ocorrências exatas dos valores de secrets ativados são trocadas por {{KEY}}; efeitos colaterais locais e resultados de execução não são reescritos. Valores codificados, com hash, com URL-encode, transformados de outra forma ou exfiltrados pela rede não podem ser inferidos e mascarados com segurança, então o código não deve retornar, transformar, imprimir ou transmitir secrets a destinos indevidos de propósito.

Detalhes do secret

Clique em Details em qualquer linha de secret para abrir a visão de detalhes.

A partir daí você pode:

• Editar o Display Name e a Description
• Gerenciar os Members — convidar colegas por e-mail e atribuir a eles o papel Admin ou Member

Clique em Save para aplicar as alterações ou em Back para voltar à lista.

Workspace vs. Personal

Ordem de resolução

Quando um workflow é executado, os secrets são resolvidos nesta ordem:

1. Os secrets de workspace são verificados primeiro e sempre resolvem em relação à identidade que está executando o workflow — quem chamou, quando é possível identificar, ou a conta de cobrança do workspace, caso contrário. Uma execução só vê os secrets de workspace que aquela identidade pode usar.
2. Os secrets pessoais entram como fallback, vindos de qualquer identidade que estiver executando:

O owner do workflow é o fallback apenas quando ninguém pode ser identificado, mas alguém do workspace configurou o trigger, já que esses workflows normalmente são construídos com as chaves do próprio owner. Uma URL pública pode ser chamada por qualquer pessoa, então ela nunca toma emprestadas as chaves de alguém — coloque em Workspace todos os secrets de que um workflow desses precisa.

Boas práticas

• Use secrets de workspace em produção, para que os workflows funcionem independentemente de quem os dispara
• Use secrets pessoais em desenvolvimento, para manter as chaves de teste separadas
• Dê nomes descritivos às chaves — STRIPE_SECRET_KEY em vez de KEY1
• Nunca deixe secrets fixos nos campos de entrada do workflow — sempre use referências {{KEY}}