Secret

Um Secret é um valor guardado uma vez no workspace e referenciado pelo nome em um passo de workflow do agente, como ${{secrets.KEY}}.

Ele existe para que um workflow possa se autenticar nos seus sistemas sem que a credencial apareça no prompt do agente, na resposta dele ou no registro da requisição que a usou.

Para que serve

• Manter credenciais fora do contexto do modelo: o agente escreve a referência, nunca o valor.
• Rotacionar uma credencial em um único lugar, sem alterar agente nenhum.
• Manter o valor fora de tudo o que é persistido — a requisição guardada em cada passo do workflow é gravada com todo valor de secret substituído por [REDACTED].

O valor é somente escrita

Nenhum endpoint, em nenhuma superfície, devolve o valor de um secret. Nem a API, nem as ferramentas MCP, nem o back office da Kobana. Ele é guardado criptografado (AES-256-GCM, vinculado à linha) e lido apenas pelo executor de workflows no momento em que monta a requisição de saída.

Se você perder o valor, substitua-o — não há como lê-lo de volta.

Schema

Campo	Tipo	Descrição
id	UUID	Id interno.
workspace_id	UUID	Workspace dono.
key	string	O identificador que o workflow escreve dentro de ${{secrets.KEY}}. Segue ^[A-Z][A-Z0-9_]{0,62}$ — letras maiúsculas, dígitos e underscores, começando por letra.
notes	string | null	Texto livre lembrando para que serve o valor.
last_used_at	datetime | null	Última vez que um passo de workflow de fato interpolou este secret. null até o primeiro uso.
created_at / updated_at	datetime

value é aceito na escrita e nunca devolvido na leitura.

Nomenclatura

A gramática é estreita de propósito: ${{secrets.A.B}} não significa nada, então uma chave com ponto seria irreferenciável. Use FINANCE_TOKEN, ERP_BASIC_AUTH, NFE_API_KEY.

Endpoints

Método	Caminho	Observações
GET	/v1/secrets	Lista. Paginação por keyset, filtrável por key.
POST	/v1/secrets	Cria. key duplicada no workspace resulta em 409 conflict.
PUT	/v1/secrets	Upsert casado por key — o caminho da rotação, sem precisar buscar o id.
GET	/v1/secrets/{id}	Lê um (sem o valor).
PATCH	/v1/secrets/{id}	Substitui value e/ou notes. key é imutável.
DELETE	/v1/secrets/{id}	Soft delete.

Escopos: inbox/secrets para ler, mais o verbo global write (ou inbox/secrets:write) para alterar.

Por que key não pode ser renomeada

Todo workflow referencia a chave pelo nome. Uma renomeação continuaria devolvendo 200 enquanto quebra silenciosamente cada passo que usava o nome antigo na próxima execução. Exclua o secret e crie o novo, ajustando o prompt do agente na mesma mudança.

Exclusão

A exclusão é soft, como em todo recurso. A partir da próxima execução, um passo que referencia a chave falha com secret \KEY` is not defined in this workspace**antes** de qualquer requisição ser enviada — esse passo falha ali em vez de chamar seu sistema sem autenticação, e os passos que o referenciam ficamskipped`.

Exemplo

{
  "id": "f1e2d3c4-b5a6-4978-8899-aabbccddeeff",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "key": "FINANCE_TOKEN",
  "notes": "Conta de serviço do ERP — rotaciona a cada 90 dias",
  "last_used_at": "2026-09-08T14:22:03.118Z",
  "created_at": "2026-06-01T09:14:00.000Z",
  "updated_at": "2026-09-01T09:14:00.000Z"
}