Credenciais
Objetivo
Credenciais são a forma de autenticar integrações máquina a máquina (M2M) com a Fluid. Cada credencial gera um par client_id + client_secret que o backend do cliente usa para obter tokens OAuth2 de curta duração.
💡 Esta página é voltada para times de engenharia que vão integrar com a Fluid via SDK, Embedded ou API. Se você só usa o console para criar fluxos e conexões, não precisa criar credenciais — siga direto para Primeiros Passos.
Em termos simples:
- o backend cria uma credencial na Fluid;
- a credencial é trocada por um token M2M via POST /oauth2/token-fluid-legacy;
- esse token é usado para chamar a API da Fluid ou para emitir bootstrap tokens de usuário, quando a experiência envolve SDK ou Embedded.
Quando usar cada escopo
Escopo | Quando usar | Exemplo de uso |
|---|---|---|
sdk | Quando a sua integração vai emitir bootstrap tokens para iniciar sessões de usuário | Backend do cliente chama a Fluid e prepara a experiência do SDK |
embed | Quando a experiência da Fluid vai rodar incorporada ao seu produto | Frontend do cliente recebe o token de sessão e renderiza o canvas embutido |
api | Quando a integração vai falar direto com a API administrativa da Fluid | Automações, operações de plataforma e gestão de recursos |
mcp | Quando um agente de IA (Claude, Cursor ou outro cliente MCP) vai se conectar ao workspace via Fluid MCP Server | Investigar execuções, monitorar ativações de FlowKit e, com confirmação, reprocessar eventos ou ativar FlowKits a partir de uma conversa com o agente |
Todos os escopos seguem o mesmo padrão de autenticação: client_id + client_secret -> token M2M -> chamadas autorizadas.
Como a credencial é usada
1. Criar a credencial
No console, acesse Configurações -> Credenciais e clique em Criar credencial.
Você precisa preencher:
Campo | O que significa | Obrigatório |
|---|---|---|
Nome | Nome legível para identificar o contexto de uso | Sim |
Escopo | sdk, embed, api ou mcp | Sim |
Slug | Identificador técnico usado no client_id | Sim |
Descrição | Observação interna | Não |
Ao salvar, a Fluid mostra:
- client_id
- client_secret uma única vez
Ação obrigatória: Guarde o client_secret em um secret manager ou variável de ambiente. Ele não fica acessível depois.
2. Trocar a credencial por token M2M
Use o fluxo OAuth2 client_credentials:
curl -X POST "https://id.api.fluidapi.io/oauth2/token-fluid-legacy" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET"Resposta esperada:
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3600,
"scope": "fluid:api"
}Esse token dura 1 hora.
3. Usar o token
Depois de obter o token M2M, há dois caminhos principais.
3.1. Chamar um endpoint autorizado pela Fluid
curl -X POST "https://id.api.fluidapi.io/users/token" \
-H "Authorization: Bearer ACCESS_TOKEN"Use esse caminho para operações que o token M2M já autoriza, como emissão de bootstrap tokens. Para rotas administrativas, use o token nas rotas protegidas correspondentes ao escopo exigido.
3.2. Emitir um bootstrap token de usuário
O bootstrap token existe para funcionar como uma credencial temporária de entrada na sessão do usuário final. Ele é emitido pelo backend da sua aplicação, não expõe o client_secret no frontend e deve ser trocado imediatamente por uma sessão final. Por padrão, ele expira em 5 minutos, é de uso único e tem esse tempo curto justamente para reduzir o risco operacional caso o token seja interceptado ou fique exposto em logs, histórico do navegador ou compartilhamento indevido.
Quando a integração envolve SDK ou Embedded, o backend usa a credencial para emitir um bootstrap token curto para o usuário final.
Exemplo com a SDK server-side:
import { FluidSDK } from "@fluidapi/sdk";
const fluid = new FluidSDK({
clientId: process.env.FLUID_CLIENT_ID,
clientSecret: process.env.FLUID_CLIENT_SECRET,
});
const { token } = await fluid.users.issueToken({
externalId: "user-123",
customerExternalId: "acme",
email: "[email protected]",
});
res.json({ token });Esse token é então enviado ao frontend, que faz o exchange para a sessão final. O fluxo completo é:
Credencial -> token M2M -> bootstrap token -> sessão do usuário final
Fluxo de autenticação do usuário final
Quando você estiver construindo SDK ou Embedded, o caminho mais comum é este:
- o backend autentica com a credencial;
- o backend emite um bootstrap token em POST /users/token;
- o frontend troca esse token em POST /users/token/exchange;
- a sessão é renovada em POST /users/token/refresh.
O client_secret nunca deve ir para o navegador.
Próximos passos
Com a credencial criada e o fluxo M2M entendido, há dois caminhos a seguir dependendo do seu objetivo agora.
- Vou implementar a integração (com API, SDK ou Embedded)
Se você já vai conectar a credencial ao backend do seu produto — seja via SDK, Embedded ou chamadas diretas à API — consulte a página SDK/API/Embedded. Lá você encontra o panorama de cada caminho, pré-requisitos e o que esperar de cada modelo de integração.
Adicionalmente, use o Fluid SDK Playground. Ele permite executar a cadeia completa — client_credentials → token M2M → bootstrap token → sessão — direto pela interface, útil para inspecionar a estrutura dos tokens retornados e isolar problemas antes de partir para o código.
- Quero testar antes de acessar APIs da Fluid
Se a intenção é validar a credencial e invocar APIs da Fluid, como OpenMetrics, use o Fluid SDK Playground. Ele permite confirmar que sua credencial está configurada corretamente.
Gerenciando credenciais
Acesse Configurações → Credenciais no menu lateral. A listagem exibe todas as credenciais do workspace com nome, escopo, Client ID parcial, status e data de último uso.
Listar
A listagem exibe:
- nome
- escopo
- client_id parcial
- status
- data de último uso
Os filtros disponíveis são:
- por nome
- por escopo
- por status (`active` ou revoked)
- por slug
Editar
Você pode editar apenas:
- display_name
- description
O escopo, o slug e o client_id são imutáveis depois da criação.
Revogar
Credenciais revogadas deixam de emitir novos tokens imediatamente. Tokens já emitidos continuam válidos até expirarem.
Use a revogação quando a credencial não deve mais ser reutilizada.
Regenerar secret
Se o client_secret for perdido, não é necessário destruir a credencial inteira. Use a ação POST /v1/tenants/{tenant_id}/credentials/{id}/regenerate-secret para gerar um novo segredo mantendo o mesmo client_id.
Isso é melhor do que revogar quando o objetivo é apenas rotacionar o segredo.
Status
Ativo A credencial está operando normalmente e pode emitir tokens.
Revogado A credencial foi desativada e não pode mais ser usada para novas emissões.
A revogação é imediata e irreversível. Antes de revogar uma credencial em uso em produção, certifique-se de que a aplicação já aponta para uma credencial substituta para evitar interrupções.
Credenciais e Customers
Quando um Bootstrap Token é emitido com um external_id novo pela primeira vez, a Fluid cria automaticamente um Customer vinculado a esse identificador. Esse Customer representa o CNPJ ou organização do usuário final dentro do workspace do seu cliente.
A gestão de Credenciais está, portanto, diretamente ligada à gestão de Customers: cada token emitido para um external_id específico vincula aquele usuário a um Customer rastreável em Gestão → Customers.
Consulte a página Customers para entender o ciclo completo de provisionamento e gestão.
Boas práticas
- Nunca exponha client_secret no frontend.
- Use uma credencial por contexto de integração.
- Separe por ambiente: desenvolvimento, homologação e produção.
- Dê nomes descritivos, como sdk-producao-acme, api-postman ou mcp-integration.
- Revogue credenciais que não são mais usadas.
- Rotacione o secret quando houver qualquer suspeita de exposição.
Troubleshooting
Erros comuns ao usar credenciais para autenticação M2M e como resolvê-los.
Resumo rápido
Se você só quiser guardar uma regra:
- Credencial autentica o backend com a Fluid.
- Token M2M autoriza as chamadas server-side.
- Bootstrap token inicia a experiência do usuário final.