Plataforma

Credenciais de API

As credenciais de API autenticam sua integração servidor a servidor com a REST API da Fluxis. Gerencie-as no Dashboard da Fluxis em /app/api-keys (apenas papéis Owner e Admin).

Visão geral

Cada par de credenciais consiste em:

Componente	Descrição
API Key ID	Identificador público enviado em toda requisição protegida como `x-fluxis-api-key`
API Secret	Segredo privado usado apenas em `POST /v1/auth/token`

Formato do Key ID

Ambiente	Prefixo	Exemplo
Development	`fxs.dev.`	`fxs.dev.a1b2c3d4-...`
Staging	`fxs.stg.`	`fxs.stg.a1b2c3d4-...`
Production	`fxs.prd.`	`fxs.prd.a1b2c3d4-...`

O segredo é exibido uma vez quando a chave é criada. Armazene com segurança — você não pode recuperá-lo novamente no dashboard.

Crie sua primeira chave de API

Siga estes passos após cadastrar-se e ativar 2FA:

Faça login no Dashboard da Fluxis:
- Staging: https://dashboard.stgfluxis.us
- Production: https://dashboard.fluxis.us
Na barra lateral, abra Developers → API Keys (caminho: /app/api-keys).
Clique para criar uma nova chave.
Defina um nome descritivo (ex.: staging-backend-integration).
Atribua os papéis read e write para uma integração de pagamento padrão.
Conclua o desafio de verificação 2FA quando solicitado.
Copie o API Secret imediatamente e armazene no gerenciador de segredos — o dashboard não o mostrará novamente.
Anote o API Key ID (fxs.stg.* ou fxs.prd.*) para usar como x-fluxis-api-key em requisições protegidas.

Apenas colaboradores Owner e Admin podem criar chaves de API. Consulte Equipe e papéis se precisar de acesso.

Próximo: troque a chave e o segredo por um token Bearer — consulte Guia de integração API — Autenticação.

Acesso ao dashboard

Abra o Dashboard da Fluxis e navegue até:

/app/api-keys

Ações disponíveis (Owner / Admin):

Ação	Descrição
List keys	Visão paginada das chaves de API da organização
Create key	Gerar nova chave + segredo (exige verificação 2FA)
Update name / roles	Alterar nome de exibição ou papéis de permissão
Update allowed IPs	Restringir requisições a faixas de IP específicas
Enable / Disable	Ativar ou desativar chave sem excluí-la
Delete	Remover permanentemente uma chave

Criar uma nova chave de API exige um desafio ativo de autenticação de dois fatores. Cadastre-se em /app/user/2fa antes da primeira criação de chave.

Papéis de API

Cada chave recebe um ou mais papéis de API:

Papel	Permissões típicas
`read`	Acesso somente leitura (listar POS, obter solicitações de pagamento, listar transações)
`write`	Criar e alterar recursos (solicitações de pagamento, reembolsos, webhooks)

Os papéis ficam na credencial e são aplicados pela camada de autorização da API. Chaves de escopo organizacional operam em todas as contas da organização; chaves de escopo de conta (quando provisionadas) ficam limitadas a uma única conta.

Fluxo de autenticação

Credenciais de API não são enviadas em cada requisição diretamente. Troque-as por um token Bearer de curta duração:

Code
curl -X POST "https://api.fluxis.us/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "fxs.prd.YOUR_KEY_ID",
    "api_secret": "YOUR_API_SECRET"
  }'

Depois chame endpoints protegidos com ambos os cabeçalhos:

Code
curl "https://api.fluxis.us/v1/pos?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID"

Não envie x-fluxis-api-key em POST /v1/auth/token — apenas o corpo JSON com api_key e api_secret.

Validade do token

Tokens de acesso expiram após 1 hora
Solicite um novo token antes da expiração
Desabilitar uma chave invalida o uso imediatamente

Lista de permissão de IP

Em /app/api-keys, você pode restringir uma chave a endereços IP de origem ou faixas CIDR específicas. Requisições de outros IPs são rejeitadas mesmo com token válido.

Deixe a lista vazia para permitir qualquer IP (não recomendado em produção).

Boas práticas de segurança

Nunca incorpore segredos de API em código client-side, apps móveis ou repositórios públicos. Credenciais pertencem apenas ao seu backend.

Use chaves separadas por ambiente — dev, staging e production nunca devem compartilhar credenciais
Aplique menor privilégio — prefira chaves read para serviços de relatório; use write apenas onde necessário
Desative chaves não usadas — desative ou exclua chaves que não precisa mais
Ative 2FA — obrigatória para criar chaves; protege o acesso ao dashboard
Monitore last_used_at — revise a atividade das chaves na lista do dashboard

Ciclo de vida das credenciais

Evento	Efeito
Key created	Segredo exibido uma vez; chave habilitada por padrão
Key disabled	Troca de token e chamadas à API falham
Key enabled	Operação normal retomada
Key deleted	Permanente; crie nova chave para substituir

A rotação de credenciais (substituir uma chave mantendo a mesma identidade lógica) é tratada pelo suporte Fluxis ou criando nova chave, migrando integrações e excluindo a antiga. Não há API pública de "rotacionar segredo no lugar" hoje.

O que as credenciais não podem fazer

Login no dashboard (colaboradores usam e-mail/senha + 2FA, não chaves de API)
Recuperação automática do segredo após a criação

Documentação relacionada

Cadastro de comerciante — criar conta e ativar 2FA
Autenticação de dois fatores — obrigatória para criar chaves
Equipe e papéis — quem pode gerenciar chaves de API
Guia de integração API — integração ponta a ponta

Last modified on October 12, 2026

Notificações de pagamento Autenticação de dois fatores