Credenciais e rotação

Selo de estado: Preview — inventário e runbook de rotação das credenciais do workspace. Atualizado em 2026-09-17. Fonte de estado: matriz de estados do produto. Limite atual do produto = Preview.

Um mapa de quais segredos existem no seu workspace, como cada um é guardado e o que trocar, rotacionar e revogar significam para cada um — porque não significam a mesma coisa.

As famílias#

A diferença não é estética: ela decide o que acontece quando você troca o valor.

Família 1a — Chaves EMITIDAS pelo produto (API de dados e service principal)#

Como é guardada. A chave de API de dados (ing_live_…) e o service principal (sp_live_…) viram um SHA-256 do valor cru, mais um prefixo de 16 caracteres guardado em claro só para você identificar a chave na lista.

Valor cru. Aparece uma única vez, na criação. Não há como reexibi-lo — o banco não tem o original.

Perdeu? Gere outra e revogue a anterior. Não existe recuperação.

Trocar = rotacionar. Aqui as duas palavras coincidem: a credencial nasce e morre dentro do ingestia.io, não existe cópia dela em outro sistema.

A antiga é recusada imediatamente? Sim. Toda requisição resolve a chave consultando o banco pelo hash e para se houver revokedAt. Não há cache de chave resolvida, nem janela de graça — a leitura vai ao banco a cada chamada.

Escopo. O service principal carrega o papel no envelope da própria credencial e cai para viewer quando o envelope está ilegível (fail-closed). Um token ing_live_… nunca é aceito como service principal, e vice-versa: o prefixo é conferido antes de qualquer consulta.

1. 1

   Chave de API (dados)

   Em Configurações → Chaves de API, gere uma nova chave, atualize seus integradores e revogue a antiga. A partir da revogação, chamadas com a chave velha respondem 401 — sem espera.

2. 2

   Service principal

   Gere um novo sp_live_… com o papel adequado, aponte o IdP/integração para ele e revogue o anterior. Revogar um SP de outro workspace é recusado (a checagem é por dono, não por id).

Família 1b — Senha de login#

Como é guardada. Hash scrypt com sal, no formato scrypt$N$sal$hash. O servidor só confere o que você digita; o valor original não fica em lugar nenhum.

Onde ela é definida. No cadastro da conta (e-mail + senha). É o único ponto do produto que grava a senha de login.

A antiga para de valer na hora? Para autenticar, sim: o login confere o hash gravado, então uma senha substituída não abre sessão nova. Mas as sessões já abertas continuam valendo: a sessão é um token assinado, guardado no navegador de quem entrou, e o servidor não mantém lista de sessões para revogar. Não há, portanto, "encerrar sessões em todos os dispositivos". Uma sessão aberta termina quando a pessoa sai ou quando o token expira.

E o cache? Não existe cache de senha. Dentro de uma mesma requisição, a sessão é resolvida uma única vez (memoização por requisição) e nada disso atravessa requisições. O que sobrevive à troca é o token já emitido — ver o parágrafo acima —, não um cache do servidor.

Família 2 — Credenciais das suas fontes de dados#

Esta é a família em que "rotacionar" é ambíguo, e onde a confusão custa caro.

Como é guardada. Duas possibilidades, por conexão:

• cifrada no banco (AES-256-GCM) — o padrão de hoje; ou
• no cofre externo de credenciais, com o banco guardando só uma referência. A referência aponta para uma versão numerada (nunca latest).

Valor cru. Você digita, o produto usa, e a interface não devolve o valor depois. Para mudar, use Substituir credencial — não existe "ver a senha atual". Mas atenção: não reexibir não é a mesma coisa que não ser recuperável. O processamento precisa autenticar no seu banco, então o valor é decifrado a cada execução.

Por isso a conexão tem um estado de rotação próprio, com três valores:

O ciclo de troca, na ordem em que acontece. Cada passo só roda se o anterior deu certo, e o relatório da tela mostra cada um:

1. garantir o segredo no cofre (idempotente);
2. criar a versão nova;
3. validar — ler a versão de volta e conferir que os campos gravados são exatamente os esperados. Sem isso, promover seria um voto de confiança;
4. promover — a referência passa a apontar para a versão nova;
5. invalidar o cache da conexão;
6. aposentar a versão anterior — desabilitada, não destruída (janela de rollback e perícia).

Se a validação (passo 3) falhar, nada é promovido: a versão nova é desabilitada e a credencial anterior continua em uso. O passo 6 é o único "melhor esforço": falhar em aposentar não desfaz uma credencial nova que já está válida — e o relatório diz que a versão antiga seguiu habilitada no cofre.

Cache. O valor resolvido fica em memória do processo, com validade de 5 minutos, e a chave do cache inclui tenant + conexão + segredo + versão. Consequências práticas:

• promover uma versão nova muda a chave, então o valor antigo não é servido por engano;
• rotação e revogação invalidam o cache na hora no processo que executou a operação;
• em outros processos (o executor dos pipelines roda em outro lugar), o teto é a validade de 5 minutos;
• o segredo nunca vai para cache externo (cache compartilhado, disco) nem para uma chave sem a versão.

Processos em andamento. A resolução acontece no início da execução. Uma execução que já começou termina com o valor que resolveu; ela não é interrompida por uma troca feita no meio. A execução seguinte resolve de novo e já usa a credencial nova — ou falha, se você revogou.

Revogação. Revogar marca a referência como revogada e desabilita a versão no cofre. Depois disso, toda resolução falha fechada. E, deliberadamente, a revogação não:

• volta para a credencial cifrada no banco (isso faria a revogação parecer aplicada sem estar);
• reabre a versão anterior;
• apaga a versão (destruir é irreversível e impediria perícia).

Sem fallback silencioso. Quando existe referência de cofre, o cofre é a única fonte. Cofre indisponível ou IAM negado interrompem a execução com mensagem acionável e código estável — nunca resolvem para um segredo global, homônimo ou de outro tenant. Referência de outro workspace ou de outra conexão é recusada antes de qualquer chamada de rede.

Família 3 — Segredos de assinatura e de cálculo#

São nossos, não da sua origem. O produto precisa do valor para assinar um token ou calcular um código — e por isso eles são cifrados (AES-256-GCM), não hasheados.

Segredo de embed do painel

• Guardado cifrado. O par é keyId (público, viaja no token) + secret.
• Rotacionar troca os dois de uma vez. Todo token já emitido para de valer na hora, porque a verificação compara o keyId do token com o keyId atual antes de olhar a assinatura.
• Atualize o segredo no seu servidor antes de rotacionar, ou o painel incorporado para junto.

Semente do MFA (TOTP)

• Guardada cifrada; o verificador recalcula os códigos de seis dígitos a partir dela.
• Limitação inventariada: o leitor tolera semente legada em texto plano (cadastros anteriores à cifra). Se a decifra falhar, o valor guardado é usado como está. Cadastros antigos podem, portanto, ainda não estar cifrados.
• Não existem códigos de recuperação de uso único no produto hoje. Esta página já os listou; não há implementação correspondente. Perder o dispositivo de MFA é um caso de suporte, não de autoatendimento — ver Suporte.

Chave da conta de serviço do workspace

• Usada para acessar os recursos de nuvem do processamento; guardada cifrada ou no cofre gerenciado.
• Rotacionar invalida a chave atual: ferramentas que usam a chave antiga param. Baixe e distribua a nova antes de rotacionar.

O que é cifra e o que é verificador (tabela de conferência)#

Esta tabela descreve a implementação atual, não uma intenção.

A chave de cifra vem de uma variável de ambiente dedicada do servidor; em produção, a ausência dela falha fechado em vez de cair num valor de desenvolvimento.

Inventário rápido#

O que vale para todas#

Três coisas — e só três — valem para todas as famílias:

• Escopo por workspace. Toda credencial resolve apenas o workspace/org que a emitiu. Nenhuma cruza clientes, e a checagem de dono acontece antes de qualquer leitura.
• Menor privilégio. Um service principal viewer é negado (403) em ações acima do papel — ver RBAC.
• Nada de segredo em log, erro, auditoria, export ou DAG. Os valores não aparecem em mensagem de erro nem em linha de log; a definição do pipeline guarda a referência da conexão, nunca a credencial.

Quando rotacionar#

• Suspeita de vazamento (segredo em log, URL compartilhada, print): trate como incidente Crítico (Suporte). Para a família 2, lembre que o passo que encerra o risco é a revogação na origem.
• Saída de pessoa com acesso ao segredo.
• Higiene periódica de credenciais de integração.

Limites#

• Chave de dados = nível workspace (sem recorte por membro). Chave por membro com RLS está no Roadmap.
• Allowlist de origens do embed é global da instância hoje (por-workspace = Roadmap) — ver Embed.
• Um único cofre externo suportado — o do próprio produto. Levar as credenciais para um cofre seu é o adicional de Gestão de Credenciais, e não está incluído no plano.
• Sem códigos de recuperação de MFA (ver família 3).
• Rotação de refresh token de alguns conectores OAuth (Bling, Conta Azul, HubSpot) não é persistida — por isso a configuração desses conectores é recusada hoje. Ver Conectores.

Erros comuns e diagnóstico#

Exemplo#

Um script da Comércio Aurora (fictícia) teve a chave ing_live_… vazada num log. Maria (owner) gera outra chave, atualiza o servidor de integração e revoga a antiga — toda chamada com a chave vazada responde 401 na hora.

Se o que tivesse vazado fosse a senha do banco de origem, o roteiro seria outro: trocar o valor na conexão resolve qual senha o ingestia.io usa, mas quem copiou a senha antiga continua entrando no banco até alguém revogá-la no banco. Só então a rotação é marcada como concluída na origem.

Resultado esperado#

• Família 1a: a chave nova funciona e a antiga responde 401 imediatamente.
• Família 1b: uma senha substituída não abre sessão nova — mas a sessão que já estava aberta continua até sair ou expirar; não há revogação de sessão.
• Família 2: a versão nova é a que o produto usa; a origem só está segura depois da revogação lá, e a conexão registra esse estado.
• Família 3: o segredo novo assina/calcula, e o que dependia do antigo para de valer na hora.
• Nenhuma credencial resolve dados de outro workspace.

Relacionados#

• Autenticação da API
• Embed SDK
• SSO e SCIM
• Conectores
• Papéis (RBAC)

Última revisão: 2026-09-17. As famílias, o ciclo de troca, o cache, o comportamento em execução e os limites acima foram conferidos contra o código do produto, não contra um princípio geral.