# 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](/pt/docs/merchant-integration/sign-up) e [ativar 2FA](/pt/docs/developers/two-factor-auth):

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

::::warning
Apenas colaboradores **Owner** e **Admin** podem criar chaves de API. Consulte [Equipe e papéis](/pt/docs/developers/team-and-roles) se precisar de acesso.
::::

Próximo: troque a chave e o segredo por um token Bearer — consulte [Guia de integração API — Autenticação](/pt/docs/developers/tutorials/api-integration-guide#etapa-2--autenticacao).

## 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 |

::::warning
Criar uma nova chave de API exige um desafio ativo de **autenticação de dois fatores**. Cadastre-se em [`/app/user/2fa`](/pt/docs/developers/two-factor-auth) 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:

```bash
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:

```bash
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"
```

::::note
**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

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

1. **Use chaves separadas por ambiente** — dev, staging e production nunca devem compartilhar credenciais
2. **Aplique menor privilégio** — prefira chaves `read` para serviços de relatório; use `write` apenas onde necessário
3. **Desative chaves não usadas** — desative ou exclua chaves que não precisa mais
4. **Ative 2FA** — obrigatória para criar chaves; protege o acesso ao dashboard
5. **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 |

::::info
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](/pt/docs/merchant-integration/sign-up) — criar conta e ativar 2FA
- [Autenticação de dois fatores](/pt/docs/developers/two-factor-auth) — obrigatória para criar chaves
- [Equipe e papéis](/pt/docs/developers/team-and-roles) — quem pode gerenciar chaves de API
- [Guia de integração API](/pt/docs/developers/tutorials/api-integration-guide) — integração ponta a ponta