Skip to main content

​
O que são Credentials?

Credentials (credenciais) são pares chave-valor criptografados que permitem armazenar informações sensíveis como API keys, tokens e secrets de forma segura. Em vez de colocar valores sensíveis diretamente no código do seu workflow, você pode referenciá-los pelo nome e o sistema irá injetá-los de forma segura em tempo de execução.

​
Por que usar Credentials?

Sem CredentialsCom Credentials
API keys hardcoded no códigoValores armazenados criptografados, referenciados por nome
Risco de expor secrets acidentalmenteSecrets nunca visíveis em logs ou UI
Difícil rotacionar chavesRotação fácil sem alterar código
Mesma chave repetida em vários workflowsFonte única de verdade para todos os workflows

​
Gerenciando Credentials

​
Acessando as Configurações de Credentials

Navegue até Configurações do Workspace → Credentials para gerenciar as credenciais do seu workspace.

​
Criando uma Credential

  1. Clique em Adicionar Credential
  2. Digite uma Chave (identificador que você usará no código, ex: SLACK_BOT_TOKEN)
  3. Digite o Valor (o secret em si)
  4. Clique em Salvar
O valor da credential é criptografado antes de ser armazenado. Uma vez salvo, você não poderá visualizar o valor novamente — apenas atualizá-lo ou deletá-lo.

​
Nomenclatura de Chaves

Escolha nomes descritivos e consistentes para suas chaves de credential: 
SLACK_BOT_TOKEN
OPENAI_API_KEY
DATABASE_PASSWORD
GITHUB_ACCESS_TOKEN
STRIPE_SECRET_KEY
Use letras maiúsculas com underscores para consistência, similar a variáveis de ambiente. Isso facilita identificar credentials no seu código.

​
Atualizando uma Credential (Rotação)

Para rotacionar uma credential:
  1. Encontre a credential na lista
  2. Clique em Editar
  3. Digite o novo valor
  4. Clique em Salvar
O novo valor entra em vigor imediatamente para novas execuções de workflow.

​
Deletando uma Credential

Deletar uma credential fará com que qualquer workflow que a referencia falhe com um erro missing_credential. Certifique-se de que nenhum workflow ativo depende da credential antes de deletar.

​
Usando Credentials em Code Execution

Em steps de Code Execution, use a função credential() para obter valores secretos em tempo de execução.

​
JavaScript/TypeScript

// Obtém o valor de uma credential
const apiKey = credential("OPENAI_API_KEY");

// Use no seu código
const response = await fetch("https://api.openai.com/v1/chat/completions", {
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  // ...
});

​
Usando Credentials em Agents

Quando um workflow executa um Agent step, todas as credentials do workspace ficam automaticamente disponíveis para o agent. Você pode instruir o agent a usar uma credential específica referenciando seu nome no prompt ou na configuração do agent. Por exemplo, você pode dizer ao agent: “Use a credential SLACK_BOT_TOKEN para enviar uma mensagem no canal #general.”
Credentials são herdadas do escopo do workflow. O agent recebe as mesmas credentials disponíveis para o workflow que o disparou.

​
Como Credentials Funcionam em Runtime

Quando um step de workflow executa:
  1. O sistema resolve todas as credentials disponíveis para o workspace
  2. Credentials são descriptografadas e injetadas no ambiente de execução do step
  3. A função credential() lê desse contexto seguro
  4. Valores de credentials são mantidos apenas em memória — nunca persistidos em logs, outputs ou estado
O sistema usa mascaramento best-effort para evitar que valores de credentials apareçam em logs. Porém, se seu código explicitamente imprimir um valor de credential, ele ainda pode ser visível.

​
Escopos de Credentials

Credentials são definidas no nível do workspace, o que significa que estão disponíveis para todos os workflows no workspace.

​
Como Funciona a Resolução

Quando seu código chama credential("KEY"):
  1. O sistema procura uma credential com essa chave no workspace
  2. Se encontrada, o valor descriptografado é retornado
  3. Se não encontrada, o step falha com erro missing_credential
credential("SLACK_BOT_TOKEN")
         ↓
    Credentials do workspace
         ↓
    Encontrada? → Retorna valor
    Não encontrada? → Erro: missing_credential
Em breve: Override de credentials no nível do workflow ou agent, permitindo usar valores diferentes para workflows específicos enquanto mantém os defaults do workspace.

​
Considerações de Segurança

​
Criptografia

Todos os valores de credentials são criptografados usando AES-256-GCM antes do armazenamento. Valores são descriptografados apenas no momento da execução e mantidos em memória pelo menor tempo necessário.

​
Controle de Acesso

  • Apenas administradores do workspace podem criar, atualizar ou deletar credentials
  • Usuários com permissão de editar/executar workflows podem referenciar credentials pela chave, mas não podem ver os valores
  • Valores de credentials nunca são retornados pela API após a criação

​
Tratamento de Erros

​
Credential Ausente

Se seu código referencia uma credential que não existe: 
// Isso lançará um erro se MY_KEY não existir
const value = credential("MY_KEY");
// Erro: missing_credential - Credential 'MY_KEY' não encontrada
Solução: Crie a credential nas Configurações do Workspace antes de executar o workflow.

​
Boa Prática: Validar no Início

Verifique as credentials necessárias no início do seu código: 
// Valida todas as credentials necessárias logo no início
const slackToken = credential("SLACK_BOT_TOKEN");
const openaiKey = credential("OPENAI_API_KEY");

if (!slackToken || !openaiKey) {
  throw new Error("Credentials necessárias ausentes");
}

// Continue com sua lógica...

​
Boas Práticas

Faça

  • Use nomes de chaves descritivos e consistentes
  • Rotacione credentials periodicamente
  • Use credentials separadas para diferentes serviços
  • Teste workflows após rotação de credentials
  • Documente para que cada credential é usada

Não Faça

  • Hardcode de secrets no código do workflow
  • Log ou print de valores de credentials
  • Compartilhar valores de credentials fora do sistema
  • Usar a mesma credential para múltiplos propósitos
  • Deletar credentials sem verificar dependências

​
Perguntas Frequentes

Não. Por razões de segurança, valores de credentials não podem ser recuperados após a criação. Você só pode atualizá-los (sobrescrever) ou deletá-los.
Cada step resolve credentials no momento da execução. Se uma credential for rotacionada no meio de uma execução, steps subsequentes usarão o novo valor. Steps já em execução continuam com o valor que obtiveram.
Credentials estão disponíveis em steps de Code Execution e Agent através da função credential(). Elas não podem ser usadas em campos de configuração do workflow ou template strings.
Não há limite rígido, mas recomendamos manter as credentials organizadas e remover as não utilizadas para manter a clareza.
Não. Credentials têm escopo em um único workspace. Cada workspace tem seu próprio conjunto isolado de credentials.
Valores de credentials podem ter até 64KB. Para secrets maiores, considere armazená-los em um secret manager dedicado e usar uma credential para guardar o token de acesso.

​
Resumo

RecursoDescrição
ArmazenamentoPares chave-valor criptografados nas configurações do workspace
AcessoVia função credential("KEY") em Code Execution e Agents
EscopoNível de workspace (todos os workflows podem acessar)
SegurançaCriptografia AES-256-GCM, nunca logado ou exposto
GerenciamentoCriar, atualizar (rotacionar), deletar via Configurações do Workspace
Credentials fornecem uma forma segura e centralizada de gerenciar valores sensíveis em seus workflows, eliminando a necessidade de secrets hardcoded e simplificando a rotação de chaves.