Credenciais

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ê os referencia pelo nome, e o Tela os injeta de forma segura em tempo de execução.

Por que usar Credentials?

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

Gerenciando Credentials

Acessando as Configurações de Credentials

Abra Configurações do Workspace → Credentials para gerenciar as credenciais do seu Workspace.

Criando uma Credential

Clique em Adicionar Credential
Digite uma Chave (identificador que você usará no código, ex: SLACK_BOT_TOKEN)
Digite o Valor (o secret em si)
Clique em Salvar

O valor da credential é criptografado antes de ser armazenado. Depois de salvo, ele não pode mais ser visualizado: você só pode atualizá-lo ou excluí-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 e sublinhados, como em variáveis de ambiente, para manter a consistência. Isso facilita identificar credentials no seu código.

Atualizando uma Credential (Rotação)

Para rotacionar uma credential:

Encontre a credential na lista
Clique em Editar
Digite o novo valor
Clique em Salvar

O novo valor entra em vigor imediatamente para novas execuções de workflow.

Excluindo uma Credential

Excluir uma credential faz qualquer workflow que a referencia falhar com o erro missing_credential. Confira se nenhum workflow ativo depende dela antes de excluir.

Usando Credentials em Execução de Código

Em etapas de Execução de Código, 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 uma etapa de Agent Existente, todas as credentials do Workspace ficam disponíveis para o Agente. O Agente nunca vê os valores: ele se refere a uma credential pelo nome, e o Tela injeta o valor no momento da chamada. Para que o Agente use uma credential específica, cite o nome dela no Objetivo ou na configuração do Agente. Por exemplo, você pode dizer ao Agente: “Use a credential SLACK_BOT_TOKEN para enviar uma mensagem no canal #general.”

Credentials são herdadas do escopo do workflow. O Agente recebe as mesmas credentials disponíveis para o workflow que o executou.

Como Credentials Funcionam em Runtime

Quando uma etapa de workflow roda:

O sistema resolve todas as credentials disponíveis para o Workspace
As credentials são descriptografadas e injetadas no ambiente de execução da etapa
A função credential() lê desse contexto seguro
Os valores ficam apenas em memória, nunca em logs, saídas ou estado

O sistema tenta mascarar os valores de credentials nos logs. Porém, se o seu código imprimir um valor explicitamente, ele ainda pode ficar 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:

Abra o workflow que deseja configurar
Clique no botão Credentials no cabeçalho do workflow
Adicione credentials específicas para este 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ário	Benefício
Princípio do menor privilégio	Workflows acessam apenas as credentials que precisam
Workflows multi-tenant	Previne acesso acidental a chaves de outros clientes
Auditorias de segurança	Documentação clara de quais secrets cada workflow usa
Onboarding de novos membros	Reduz risco de workflows mal configurados

Configurando a Allowlist

Abra o workflow que deseja configurar
Clique no botão Credentials no cabeçalho do workflow
Vá para a aba Usage Permissions
Ative as credentials a 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, inclua todas as credentials de que o seu workflow precisa. Uma credential ausente faz 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 excluir 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

Colocar secrets direto no código do workflow
Imprimir valores de credentials em logs
Compartilhar valores de credentials fora do sistema
Usar a mesma credential para vários fins
Excluir credentials sem verificar dependências

Perguntas Frequentes

Posso ver o valor de uma credential após criá-la?

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 excluí-los.

O que acontece se eu rotacionar uma credential durante uma execução de workflow?

Cada etapa resolve as credentials no momento da execução. Se uma credential for rotacionada no meio de uma execução, as etapas seguintes usam o novo valor. Etapas já em execução continuam com o valor que obtiveram.

Posso usar credentials na configuração do workflow?

Credentials estão disponíveis em etapas de Execução de Código e Agent Existente por meio da função credential(). Elas não podem ser usadas em campos de configuração do workflow nem em template strings.

Existe um limite de número de credentials?

Não há limite rígido, mas recomendamos manter as credentials organizadas e remover as não utilizadas para manter a clareza.

Credentials são compartilhadas entre workspaces?

Não. Credentials têm escopo em um único workspace. Cada workspace tem seu próprio conjunto isolado de credentials.

Como credentials com escopo de workflow interagem com credentials de workspace?

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 que acontece se eu configurar uma allowlist mas esquecer uma credential?

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.

Posso usar tanto credentials com escopo de workflow quanto 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.

E se o valor da minha credential for muito longo?

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

Recurso	Descrição
Armazenamento	Pares chave-valor criptografados nas configurações do workspace
Acesso	Via função `credential("KEY")` em Execução de Código e Agentes
Escopo	Nível de workspace ou nível de workflow (com capacidade de override)
Allowlist	Lista opcional de credentials permitidas por workflow
Segurança	Criptografia AES-256-GCM, nunca logado ou exposto
Gerenciamento	Criar, atualizar (rotacionar) e excluir via Configurações do Workspace ou cabeçalho 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.

Primeiros passos

Construir

Testar

Operar

Integrar

Credenciais

O que são Credentials?

Por que usar Credentials?

Gerenciando Credentials

Acessando as Configurações de Credentials

Criando uma Credential

Nomenclatura de Chaves

Atualizando uma Credential (Rotação)

Excluindo uma Credential

Usando Credentials em Execução de Código

JavaScript/TypeScript

Usando Credentials em Agents

Como Credentials Funcionam em Runtime

Escopos de Credentials

Credentials de Workspace

Credentials com Escopo de Workflow

Allowlist de Credentials

Por que Usar uma Allowlist?

Configurando a Allowlist

Considerações de Segurança

Criptografia

Controle de Acesso

Tratamento de Erros

Credential Ausente

Boa Prática: Validar no Início

Boas Práticas

Faça

Não Faça

Perguntas Frequentes

Resumo

​O que são Credentials?

​Por que usar Credentials?

​Gerenciando Credentials

​Acessando as Configurações de Credentials

​Criando uma Credential

​Nomenclatura de Chaves

​Atualizando uma Credential (Rotação)

​Excluindo uma Credential

​Usando Credentials em Execução de Código

​JavaScript/TypeScript

​Usando Credentials em Agents

​Como Credentials Funcionam em Runtime

​Escopos de Credentials

​Credentials de Workspace

​Credentials com Escopo de Workflow

​Allowlist de Credentials

​Por que Usar uma Allowlist?

​Configurando a Allowlist

​Considerações de Segurança

​Criptografia

​Controle de Acesso

​Tratamento de Erros

​Credential Ausente

​Boa Prática: Validar no Início

​Boas Práticas

Faça

Não Faça

​Perguntas Frequentes

​Resumo

O que são Credentials?

Por que usar Credentials?

Gerenciando Credentials

Acessando as Configurações de Credentials

Criando uma Credential

Nomenclatura de Chaves

Atualizando uma Credential (Rotação)

Excluindo uma Credential

Usando Credentials em Execução de Código

JavaScript/TypeScript

Usando Credentials em Agents

Como Credentials Funcionam em Runtime

Escopos de Credentials

Credentials de Workspace

Credentials com Escopo de Workflow

Allowlist de Credentials

Por que Usar uma Allowlist?

Configurando a Allowlist

Considerações de Segurança

Criptografia

Controle de Acesso

Tratamento de Erros

Credential Ausente

Boa Prática: Validar no Início

Boas Práticas

Perguntas Frequentes

Resumo