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 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 quando usar cada tipo tipo 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 todos os tipos 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 tipo sdk , embed ou api 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 "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 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 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 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, tipo, client id parcial, status e data de último uso listar a listagem exibe nome tipo client id parcial status data de último uso os filtros disponíveis são por nome por tipo por status (`active` ou revoked ) por slug editar você pode editar apenas display name description o tipo, 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 ou api postman 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 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 { "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 confirme que o client id exibido na listagem do console começa exatamente igual ao usado no backend se houve regeneração recente do secret, atualize a variável de ambiente do backend com o novo valor se a credencial estiver revogada, crie uma nova credencial e atualize a integração para apontar para ela 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