> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebanking.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar suas requisições na API PIX Bacen

## Visão Geral

A API PIX Bacen utiliza o mesmo sistema de autenticação da API padrão Fire Banking. Todas as requisições devem incluir um token Bearer válido no header `Authorization`.

<Info>
  A autenticação é idêntica à [API padrão](/api-reference/guides/authentication). Se você já possui credenciais, pode usá-las diretamente.
</Info>

## Obtendo o Token

### Endpoint

```
POST /oauth/token
```

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.public.firebanking.com.br/oauth/token \
    -H "Content-Type: application/json" \
    -d '{
      "clientId": "seu-client-id",
      "clientSecret": "seu-client-secret"
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.public.firebanking.com.br/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      clientId: 'seu-client-id',
      clientSecret: 'seu-client-secret',
    }),
  });

  const { access_token } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.public.firebanking.com.br/oauth/token',
      json={
          'clientId': 'seu-client-id',
          'clientSecret': 'seu-client-secret'
      }
  )

  access_token = response.json()['access_token']
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pix:read pix:write balance:read"
}
```

## Usando o Token

Inclua o token em todas as requisições da API PIX Bacen:

```bash theme={null}
curl -X PUT https://api.public.firebanking.com.br/cob/abc123 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{...}'
```

## Parâmetros de Autenticação

<ParamField body="clientId" type="string" required>
  Identificador único da sua aplicação. Fornecido durante o cadastro.
</ParamField>

<ParamField body="clientSecret" type="string" required>
  Chave secreta da sua aplicação. Deve ter entre 8 e 64 caracteres.

  <Warning>
    Nunca exponha o `clientSecret` em código frontend ou repositórios públicos.
  </Warning>
</ParamField>

## Campos da Resposta

<ResponseField name="access_token" type="string">
  Token JWT para autenticação nas requisições.
</ResponseField>

<ResponseField name="token_type" type="string">
  Tipo do token. Sempre `"Bearer"`.
</ResponseField>

<ResponseField name="expires_in" type="number">
  Tempo de vida do token em segundos. Padrão: 3600 (1 hora).
</ResponseField>

<ResponseField name="scope" type="string">
  Escopos de permissão do token.
</ResponseField>

## Renovação do Token

O token expira após `expires_in` segundos. Implemente renovação automática:

```typescript theme={null}
class TokenManager {
  private token: string | null = null;
  private expiresAt: number = 0;

  async getToken(): Promise<string> {
    // Renovar 5 minutos antes de expirar
    if (!this.token || Date.now() >= this.expiresAt - 300000) {
      await this.refreshToken();
    }
    return this.token!;
  }

  private async refreshToken(): Promise<void> {
    const response = await fetch('https://api.public.firebanking.com.br/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        clientId: process.env.CLIENT_ID,
        clientSecret: process.env.CLIENT_SECRET,
      }),
    });

    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + (data.expires_in * 1000);
  }
}
```

## Erros de Autenticação

| Código | Descrição           | Solução                                         |
| ------ | ------------------- | ----------------------------------------------- |
| 401    | Token não fornecido | Inclua o header `Authorization: Bearer <token>` |
| 401    | Token inválido      | Verifique se o token está correto e não expirou |
| 401    | Token expirado      | Obtenha um novo token via `/oauth/token`        |
| 403    | Permissão negada    | Verifique os escopos do token                   |

## Boas Práticas

<AccordionGroup>
  <Accordion title="Armazene credenciais com segurança">
    * Use variáveis de ambiente
    * Nunca commite credenciais no código
    * Use secret managers em produção (AWS Secrets Manager, HashiCorp Vault)
  </Accordion>

  <Accordion title="Implemente cache de token">
    * Cache o token até próximo da expiração
    * Renove alguns minutos antes de expirar
    * Evite requisições desnecessárias ao endpoint de token
  </Accordion>

  <Accordion title="Use HTTPS sempre">
    * Todas as requisições devem usar HTTPS
    * Verifique certificados SSL/TLS
    * Configure timeouts apropriados
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Ativação" icon="toggle-on" href="/pix-bacen/activation">
    Ative o modo PIX Bacen na sua conta
  </Card>

  <Card title="Criar Cobrança" icon="qrcode" href="/pix-bacen/endpoints/cob">
    Faça sua primeira cobrança
  </Card>
</CardGroup>