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

# Autenticação

> Como funcionam as credenciais e a autenticação na Velfy Payments

# Autenticação

> Entenda as credenciais da Velfy Payments e como autenticar suas requisições

Todas as chamadas à API pública (`/api/v1/*`) precisam ser autenticadas. A Velfy usa um modelo de duas chaves, no mesmo padrão adotado pelas principais APIs de pagamento do mercado.

## Suas credenciais

Ao ativar sua conta, você recebe duas chaves:

<CardGroup cols={2}>
  <Card title="Public Key" icon="eye">
    Formato `pk_...`. Pode ser exposta em código client-side — é a chave usada, por exemplo, no fluxo de tokenização de cartão direto do navegador do comprador.
  </Card>

  <Card title="Secret Key" icon="eye-slash">
    Formato `sk_...`. **Nunca** deve ser exposta publicamente — é ela quem autentica as chamadas feitas pelo seu backend.
  </Card>
</CardGroup>

## Como a autenticação funciona

As rotas de backend (criar cobrança, consultar transação, solicitar saque, etc.) usam **HTTP Basic Auth**, combinando as duas chaves:

```bash theme={null}
# usuário = secret key, senha = public key
echo -n "sk_xxx:pk_xxx" | base64
```

```text theme={null}
Authorization: Basic base64(secret_key:public_key)
```

Já o fluxo de **tokenização de cartão** (que roda no navegador do cliente) usa apenas a Public Key, passada como query param — assim a Secret Key nunca precisa chegar perto do front-end.

<Info>
  Requisições sem um header `Authorization` válido recebem `401 Unauthorized`.
</Info>

## Boas práticas

<AccordionGroup>
  <Accordion title="Onde guardar as chaves" icon="lock">
    * Use variáveis de ambiente — nunca chaves hardcoded no código-fonte
    * Não versione arquivos `.env` com credenciais reais
    * Restrinja o acesso às chaves apenas a quem realmente precisa
  </Accordion>

  <Accordion title="O que evitar" icon="triangle-exclamation">
    * Não exponha a Secret Key em código client-side, repositórios públicos ou logs
    * Não compartilhe chaves via chat ou e-mail
  </Accordion>

  <Accordion title="Monitoramento" icon="chart-line">
    * Acompanhe o uso das suas chaves e configure alertas para atividade fora do padrão
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="PIX" icon="qrcode" href="/guides/pix">
    Comece a receber pagamentos PIX
  </Card>

  <Card title="Referência técnica" icon="book" href="/api-reference/payments/authentication">
    Veja exemplos completos em cURL, Node.js e Python
  </Card>
</CardGroup>