Embedding Guide

19 min

Incorporando a Fluid no seu produto

A Fluid foi projetada para ser incorporada diretamente no seu produto. Seus customers vivenciam a Fluid como parte nativa da sua aplicação — sem credenciais separadas, sem logins adicionais e sem troca de contexto.

Existem duas formas de incorporar a Fluid, dependendo do quanto de controle você quer sobre a experiência do usuário.

Cenários de integração

Cenário 1 — White-label

Você redireciona seu customer para o console hospedado da Fluid (console.fluidapi.io), que abre em uma nova aba ou frame. A Fluid cuida de toda a interface.

Ideal para: times que querem uma experiência de integração completa sem nenhum trabalho de frontend.

Sua aplicação  ──(redirect)──►  console.fluidapi.io
                                  (interface hospedada pela Fluid)

Cenário 2 — SDK Incorporada

Você constrói sua própria interface usando a SDK de browser da Fluid (@fluidapi/js). Seus customers nunca saem da sua aplicação. Você tem controle total sobre design, layout e experiência do usuário.

Ideal para: times que querem entregar uma experiência profundamente nativa e manter o customer journey dentro do próprio produto.

Sua aplicação  ──(chamadas de API)──►  API Fluid
 (@fluidapi/js)                          (sua UI, seu design)

Ambos os cenários usam o mesmo modelo de autenticação e a mesma API. A diferença está apenas em quem renderiza a interface.

Como funciona a autenticação

A Fluid autentica seus customers através do seu sistema de autenticação existente. Seus customers nunca criam uma conta na Fluid nem gerenciam credenciais Fluid.

O fluxo é direto:

1. Seu backend identifica o customer (ele já está logado na sua aplicação)
2. Seu backend solicita um token de acesso de curta duração à Fluid
3. Esse token é repassado ao seu frontend
4. Seu frontend o usa para acessar a Fluid em nome do customer

Sem redirecionamentos para uma página de login externa. Sem telas de consentimento OAuth. Sem senha adicional para seu customer memorizar.

O que você precisa no seu backend

Uma única chamada de API usando 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',         // seu ID interno de usuário
  customerExternalId: 'acme',     // seu ID interno de customer/organização
  email: '[email protected]',
})

É isso. Você recebe um token. Repasse ao seu frontend.

Cenário 1 — White-label: guia de implementação

Passo 1 — Emita um token no seu backend

const { token } = await fluid.users.issueToken({ externalId, customerExternalId })

Passo 2 — Monte a URL de redirecionamento

const url = `https://console.fluidapi.io#token=${token}`

Passo 3 — Direcione seu customer

Abra a URL em uma nova aba, um iframe ou um redirecionamento completo. A Fluid cuida do restante. O token é válido por 5 minutos e é de uso único — torna-se inválido no momento em que o console carrega.

Cenário 2 — SDK Incorporada: guia de implementação

Passo 1 — Instale a SDK de browser

npm install @fluidapi/js

Passo 2 — Emita um token no seu backend e exponha ao seu frontend

// Endpoint no seu backend
app.get('/fluid-token', requireAuth, async (req, res) => {
  const { token } = await fluid.users.issueToken({
    externalId: req.user.id,
    customerExternalId: req.user.customerId,
  })
  res.json({ token })
})

Passo 3 — Autentique no seu frontend

import { FluidJS } from '@fluidapi/js'

const fluid = new FluidJS({ baseUrl: 'https://id.api.fluidapi.io' })

// Obtenha o token do seu backend e autentique
const { token } = await fetch('/fluid-token').then(r => r.json())
await fluid.authenticate({ token })

Passo 4 — Comece a chamar a API Fluid

// Liste as ativações de flowkits do seu customer
const flowkits = await fluid.flowkits.list()

// Crie uma conexão ou fluxo para esse customer
const flow = await fluid.flows.create({ name: 'Meu fluxo' })

O gerenciamento de sessão é responsabilidade da SDK. Os access tokens são armazenados em memória e renovados automaticamente antes de expirar. Você chama fluid.flowkits.list() e sempre recebe uma resposta válida — a SDK cuida do restante.

Segurança e conformidade com OAuth 2.0

Você nunca assina tokens

Algumas soluções de embedding exigem que seu backend gere e assine criptograficamente JWTs usando uma chave privada que eles provisionam. Isso significa implementar assinatura RS256, gerenciar material criptográfico e lidar com rotação de chaves.

A Fluid adota uma abordagem diferente: seu backend faz uma chamada autenticada à API e recebe um token de volta. Não há criptografia do seu lado. A infraestrutura da Fluid emite e assina tudo.

Suas credenciais nunca chegam ao browser

Seu FLUID_CLIENT_ID e FLUID_CLIENT_SECRET são usados exclusivamente no seu backend. Eles nunca são repassados ou armazenados no browser em nenhum momento do fluxo. O token que seu frontend recebe é um artefato de curta duração e uso único — não uma credencial.

Tokens de sessão de uso único

O token emitido por issueToken() só pode ser usado uma vez. No momento em que seu frontend se autentica com ele, ele é invalidado server-side. Interceptar o token após esse ponto não tem utilidade. O token também expira em 5 minutos independentemente do uso.

Conformidade com OAuth 2.0

A autenticação da Fluid é construída sobre OAuth 2.0 (RFC 6749) e RFC 8693 (OAuth 2.0 Token Exchange). Os access tokens usados nas sessões dos seus customers são emitidos por um authorization server em conformidade com os padrões e podem ser validados por qualquer sistema compatível com OAuth 2.0 via introspection ou endpoints JWKS padrão.

Isso significa que os tokens da Fluid funcionam com sua infraestrutura existente: API gateways, sistemas de logging e ferramentas de segurança que entendem OAuth 2.0 não precisam de tratamento especial.

Renovação automática de sessão

A SDK de browser gerencia o ciclo de vida completo da sessão. Os access tokens são renovados automaticamente antes de expirar usando um mecanismo de rotação server-side — o segredo de renovação nunca passa pelo browser. Da perspectiva da sua aplicação, fluid.getAccessToken() sempre retorna um token válido ou lança um erro caso a sessão tenha expirado e não possa ser recuperada.

Comparando os dois cenários

	White-label	SDK Incorporada
Trabalho de frontend necessário	Nenhum	Sim
Customização de UI	Nenhuma	Controle total
Customer permanece na sua aplicação	Não (nova aba / frame)	Sim
Tempo até a primeira integração	Minutos	Horas
Recomendado para	Lançar rápido, validar a integração	Produto maduro, requisitos de UX nativos

Os dois cenários não são mutuamente exclusivos. Alguns times começam com White-label para validar a integração rapidamente e migram para a SDK Incorporada conforme o produto amadurece e os requisitos de design crescem.

Próximos passos

Instalar @fluidapi/sdk — referência da SDK server-side

Instalar @fluidapi/js — referência da SDK de browser

Referência da API — documentação completa da API Fluid

Fale com a gente — se precisar de ajuda para escolher o caminho de integração ideal