--- title: Credenciais slug: credenciais docTags: createdAt: 2026-04-24T13:17:14.314Z --- ## 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. :::hint{type="info"} 💡 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: 1. o backend cria uma credencial na Fluid; 2. a credencial é trocada por um token M2M via `POST /oauth2/token-fluid-legacy`; 3. 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. :::hint{type="info"} Credenciais não são [API Keys](docId\:U9RzUlsUP_oXxCqF5Mu_8) permanentes. Use Credenciais quando seu backend precisa falar com a Fluid via OAuth2. Use [API Keys](docId\:U9RzUlsUP_oXxCqF5Mu_8) apenas nos fluxos onde a chave precisa permanecer válida por tempo indeterminado, como webhooks externos. ::: ![](https://api.archbee.com/api/optimize/G1NTw6yAi4RDUYbsU8csp/p7QnQyCfep5JU2vHECFQ8_image.png) ## 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 :::hint{type="warning"} **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`: ```shell 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: ```json { "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** ```shell 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** :::hint{type="info"} 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: ```javascript 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: "alice@acme.com", }); 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: 1. o backend autentica com a credencial; 2. o backend emite um bootstrap token em `POST /users/token`; 3. o frontend troca esse token em `POST /users/token/exchange`; 4. 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. :::Heading{depth="3" indent="1"} 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](docId\:G-img-3sMA6FojcjvlEpr). 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](https://playground.fluidapi.io). 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. :::Heading{depth="3" indent="1"} 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](https://playground.fluidapi.io/). 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. ![](https://api.archbee.com/api/optimize/G1NTw6yAi4RDUYbsU8csp/Ir_yPodehZf8ZfmRdttx5-20260424-191132.gif) ### 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. :::hint{type="warning"} 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. :::ExpandableHeading ### 401 — invalid\_client Retornado pelo endpoint POST `/oauth2/token-fluid-legacy` quando o `client_id` ou o `client_secret` informados não correspondem a uma credencial válida. **Resposta da API:** ```json { "error": "invalid_client", "error_description": "invalid client credentials" } ``` **Causas mais comuns:** - O client\_id ou o client\_secret foram copiados com espaços, quebras de linha ou caracteres faltando - A credencial foi revogada — verifique o status em **Configurações → Credenciais** - O client\_secret está desatualizado após uma regeneração — o segredo anterior deixa de funcionar imediatamente - A credencial foi criada em outro workspace ou ambiente (homologação vs. produção) diferente do que está sendo usado no backend **Como resolver:** 1. Confirme que o client\_id exibido na listagem do console começa exatamente igual ao usado no backend 2. Se houve regeneração recente do secret, atualize a variável de ambiente do backend com o novo valor 3. Se a credencial estiver revogada, crie uma nova credencial e atualize a integração para apontar para ela 4. Se nada disso resolver, gere um novo secret pela tela de detalhes da credencial e teste novamente ::: ## 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.