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

# Autenticação

> Como autenticar suas requisições na API pública da UvviPay

A API pública utiliza autenticação via **dois headers obrigatórios** em toda requisição. A criação de subconta exige ainda um header de **idempotência**.

## Headers obrigatórios

| Header              | Obrigatoriedade                    | Descrição                                                           |
| ------------------- | ---------------------------------- | ------------------------------------------------------------------- |
| `client-id`         | Sempre                             | Identificador público da sua credencial                             |
| `client-secret`     | Sempre                             | Secret da sua credencial. Nunca exponha em código client-side       |
| `x-idempotency-key` | Somente em `POST /v1/submerchants` | UUID v4 único por operação lógica para evitar duplicação em retries |

## Exemplo

```bash theme={null}
curl -X POST https://api.uvvipay.com.br/v1/submerchants \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "x-idempotency-key: 5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f" \
  -F "documentNumber=12345678000199" \
  -F "documentType=cnpj" \
  -F "phone=11999999999"
```

## Idempotência

Apenas o endpoint `POST /v1/submerchants` exige o header `x-idempotency-key`. Envie um UUID gerado pelo seu sistema; se a requisição for repetida com a mesma chave e mesmo payload, você receberá a mesma resposta da primeira execução — evitando duplicidade.

Se a chave for reutilizada com payload diferente, a API responde **HTTP 409 Conflict**.

## Rate limit

Os endpoints de subcontas (`/v1/submerchants` — criação, atualização cadastral, atualização de taxas e atualização de conta bancária) têm limite de **5 requisições por minuto** por credencial. Se exceder, você recebe **HTTP 429 Too Many Requests**.

O endpoint do Cofre (`POST /v1/vault/tokenize`) tem limite de **30 requisições por minuto** por IP.

<Warning>
  Nunca exponha `client-secret` no front-end ou em repositórios públicos. Faça a chamada sempre a partir do seu backend.
</Warning>