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 podem ser definidas em dois níveis:
  • Nível de workspace: Disponíveis para todos os workflows no workspace (padrão)
  • Nível de workflow: Específicas para um único workflow, sobrescrevendo credentials do workspace com a mesma chave

​
Credentials de Workspace

Credentials de workspace são o escopo padrão. Elas ficam disponíveis para todos os workflows e servem como fallback quando não existe uma credential com escopo de workflow.

​
Credentials com Escopo de Workflow

Você pode criar credentials que são específicas para um único workflow. Isso é útil quando:
  • Um workflow precisa de uma API key diferente do padrão do workspace
  • Você quer isolar credentials por motivos de segurança
  • Diferentes workflows se conectam a ambientes diferentes (staging vs produção)
Para gerenciar credentials com escopo de workflow:
  1. Abra o workflow que deseja configurar
  2. Clique no botão Credentials no header do workflow
  3. Adicione credentials específicas para este workflow
Modal de credentials do workflow
Credentials com escopo de workflow que tenham a mesma chave que credentials do workspace irão sobrescrever o valor do workspace apenas para aquele workflow específico.

​
Allowlist de Credentials

Para controle adicional de segurança, você pode definir uma allowlist (lista de permissão) de credentials para cada workflow. Quando uma allowlist está configurada, apenas as credentials especificadas ficam acessíveis durante a execução do workflow.

​
Por que Usar uma Allowlist?

CenárioBenefício
Princípio do menor privilégioWorkflows acessam apenas as credentials que precisam
Workflows multi-tenantPrevine acesso acidental a chaves de outros clientes
Auditorias de segurançaDocumentação clara de quais secrets cada workflow usa
Onboarding de novos membrosReduz risco de workflows mal configurados

​
Configurando a Allowlist

  1. Abra o workflow que deseja configurar
  2. Clique no botão Credentials no header do workflow
  3. Vá para a aba Usage Permissions
  4. Ative as credentials que este workflow deve ter acesso
Configuração de allowlist de credentials
Se nenhuma allowlist estiver definida, o workflow tem acesso a todas as credentials do workspace (comportamento retrocompatível).
Ao usar uma allowlist, certifique-se de incluir todas as credentials que seu workflow precisa. Credentials ausentes farão o workflow falhar em tempo de execução.

​
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.
Credentials com escopo de workflow têm prioridade. Se um workflow tem uma credential com escopo de workflow com chave API_KEY e o workspace também tem API_KEY, o workflow usará seu próprio valor com escopo de workflow. Outros workflows sem uma API_KEY com escopo de workflow continuarão usando o valor do workspace.
O workflow falhará com erro missing_credential quando tentar acessar a credential que não está na allowlist. Certifique-se de testar seus workflows após configurar uma allowlist.
Sim. A allowlist controla quais chaves de credential são acessíveis, e credentials com escopo de workflow fornecem os valores. Se uma chave está na allowlist, o sistema primeiro verificará se há um valor com escopo de workflow, depois fará fallback para credentials do workspace.
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 ou nível de workflow (com capacidade de override)
AllowlistLista opcional de credentials permitidas por workflow
SegurançaCriptografia AES-256-GCM, nunca logado ou exposto
GerenciamentoCriar, atualizar (rotacionar), deletar via Configurações do Workspace ou header do Workflow
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. Com credentials com escopo de workflow e allowlists, você tem controle granular sobre quais secrets cada workflow pode acessar.