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

> Como autenticar requisições na API de pagamentos Velfy

# Autenticação e Credenciais

> Como obter e autenticar suas requisições na API Velfy Payments

Para começar a integrar com a Velfy Payments, você precisa das suas credenciais de API. Este guia mostra como elas funcionam e como usá-las para autenticar suas requisições.

## 🔑 Passo 1: Suas Credenciais

Ao ativar sua conta, você recebe duas chaves:

<CardGroup cols={2}>
  <Card title="🔑 Public Key" color="#16A34A" icon="eye">
    **Formato**: `pk_...`

    Pode ser exposta em código client-side, como no fluxo de tokenização de cartão
  </Card>

  <Card title="🔒 Secret Key" color="#631286" icon="eye-slash">
    **Formato**: `sk_...`

    **NUNCA** exponha esta chave publicamente — ela autentica todas as chamadas ao seu backend
  </Card>
</CardGroup>

## 🔐 Passo 2: Autenticando Requisições

As rotas da API pública (`/api/v1/*`) usam **HTTP Basic Auth**, combinando as duas chaves em Base64:

```bash theme={null}
# Codifique suas credenciais em Base64
echo -n "pk_xxx:sk_xxx" | base64
# Resultado: cGtfeHh4OnNrX3h4eA==
```

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

### Exemplo de requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.velfy.com/api/v1/transactions' \
    -u "sk_xxx:pk_xxx" \
    -H 'Content-Type: application/json' \
    -d '{ "paymentMethod": "pix", "amount": 10000 }'
  ```

  ```js Node.js theme={null}
  const credentials = Buffer.from(
    `${process.env.VELFY_PUBLIC_KEY}:${process.env.VELFY_SECRET_KEY}`
  ).toString('base64')

  const response = await fetch('https://api.velfy.com/api/v1/transactions', {
    method: 'POST',
    headers: {
      Authorization: `Basic ${credentials}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  })
  ```

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

  credentials = base64.b64encode(f"{secret_key}:{public_key}".encode()).decode()

  response = requests.post(
      "https://api.velfy.com/api/v1/transactions",
      headers={
          "Authorization": f"Basic {credentials}",
          "Content-Type": "application/json",
      },
      json=payload,
  )
  ```
</CodeGroup>

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

## 🛡️ Segurança das Credenciais

<Warning>
  Mantenha sua **Secret Key** segura e nunca a exponha em código client-side, repositórios públicos ou logs.
</Warning>

### ✅ Boas Práticas

* **Use variáveis de ambiente** para armazenar suas credenciais
* **Restrinja o acesso** apenas aos desenvolvedores necessários
* **Monitore o uso** das chaves nas suas requisições
* **Utilize a Public Key** para fluxos client-side, como a tokenização de cartão

### ❌ Práticas a Evitar

* Não commite chaves no código-fonte
* Não inclua credenciais em arquivos de configuração versionados
* Evite logs que possam expor as chaves
* Não compartilhe suas chaves via chat ou e-mail

### Exemplo de configuração segura

```bash .env theme={null}
VELFY_PUBLIC_KEY=pk_xxx
VELFY_SECRET_KEY=sk_xxx
```

```js config.js theme={null}
const config = {
  publicKey: process.env.VELFY_PUBLIC_KEY,
  secretKey: process.env.VELFY_SECRET_KEY,
}

export default config
```

***

## 🎯 Próximos Passos

<CardGroup cols={2}>
  <Card title="📝 Criando Transações" color="#631286" icon="rectangle-list" href="/api-reference/payments/transactions">
    Veja como usar o endpoint de criação de cobranças
  </Card>

  <Card title="💰 PIX" color="#631286" icon="qrcode" href="/api-reference/payments/pix">
    Comece a receber pagamentos PIX
  </Card>
</CardGroup>