> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Armazene e gerencie com segurança API keys, tokens e secrets para uso nos seus workflows

## 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 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

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**

<Note>
  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.
</Note>

### 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
```

<Tip>
  Use letras maiúsculas com underscores para consistência, similar a variáveis de ambiente. Isso facilita identificar credentials no seu código.
</Tip>

### 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

<Warning>
  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.
</Warning>

## 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

```javascript theme={null}
// 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."*

<Note>
  Credentials são herdadas do escopo do workflow. O agent recebe as mesmas credentials disponíveis para o workflow que o disparou.
</Note>

## 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

<Note>
  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.
</Note>

## 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

<Frame>
  <img src="https://mintcdn.com/meistrari/4B3NEQIMQOg_kLNY/images/credentials/prompt-credentials.png?fit=max&auto=format&n=4B3NEQIMQOg_kLNY&q=85&s=0cbf699ae08ca81943a4431b12b4d1b9" alt="Modal de credentials do workflow" width="1580" height="1410" data-path="images/credentials/prompt-credentials.png" />
</Frame>

<Note>
  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.
</Note>

## 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

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

<Frame>
  <img src="https://mintcdn.com/meistrari/4B3NEQIMQOg_kLNY/images/credentials/allowlist.png?fit=max&auto=format&n=4B3NEQIMQOg_kLNY&q=85&s=5439bf423ea8f7a335a239e9600803f4" alt="Configuração de allowlist de credentials" width="1562" height="1398" data-path="images/credentials/allowlist.png" />
</Frame>

<Tip>
  Se nenhuma allowlist estiver definida, o workflow tem acesso a todas as credentials do workspace (comportamento retrocompatível).
</Tip>

<Warning>
  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.
</Warning>

## 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:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Faça" icon="check" color="#22c55e">
    * 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
  </Card>

  <Card title="Não Faça" icon="xmark" color="#ef4444">
    * 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
  </Card>
</CardGroup>

## Perguntas Frequentes

<AccordionGroup>
  <Accordion title="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 deletá-los.
  </Accordion>

  <Accordion title="O que acontece se eu rotacionar uma credential durante uma execução de workflow?">
    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.
  </Accordion>

  <Accordion title="Posso usar credentials na configuração do workflow?">
    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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Resumo

| Recurso           | Descrição                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------- |
| **Armazenamento** | Pares chave-valor criptografados nas configurações do workspace                             |
| **Acesso**        | Via função `credential("KEY")` em Code Execution e Agents                                   |
| **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), 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.