# Autenticação

Como gerar sua chave, enviá-la em cada requisição e mantê-la segura.

Toda requisição precisa da sua chave de API no header `Authorization`, no formato `Bearer`. Não há login, token de sessão nem refresh: a chave é a credencial completa.

_Requisição_

```bash
curl https://novexfinance.com.br/api/v1/ping \
  -H "Authorization: Bearer nvx_live_a1b2c3d4e5f6…"
```

```php
$ch = curl_init('https://novexfinance.com.br/api/v1/ping');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('NOVEX_API_KEY'),
        'Content-Type: application/json',
    ],
]);
$body = json_decode(curl_exec($ch), true);
```

```js
const res = await fetch('https://novexfinance.com.br/api/v1/ping', {
  headers: {
    'Authorization': `Bearer ${process.env.NOVEX_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const data = await res.json();
```

```python
import os, requests

res = requests.get(
    'https://novexfinance.com.br/api/v1/ping',
    headers={'Authorization': f'Bearer {os.environ["NOVEX_API_KEY"]}'},
    timeout=30,
)
data = res.json()
```

_Resposta 200_

```json
{
  "object": "ping",
  "authenticated": true,
  "account_id": "acct_42",
  "server_time": "2026-08-07T14:32:10-03:00",
  "api_version": "v1"
}
```

> ℹ️ Use `GET /v1/ping` como primeiro teste da integração. Ele confirma três coisas de uma vez: a chave é válida, o header chegou até nós e a conta está ativa.

## Gerar uma chave

### Entre no painel

Acesse [Configurações → API Keys](https://novexfinance.com.br/app/api-keys) com a sua conta Novex.

---

### Gere a chave

Dê um nome que identifique onde ela vai ser usada — `loja-producao`, `erp-interno`. Se um dia precisar revogar, você saberá exatamente o que vai parar.

---

### Copie na hora

A chave aparece **uma única vez**. Guardamos apenas um hash dela — nem nós conseguimos recuperá-la depois. Se perder, revogue e gere outra.

As chaves começam com `nvx_live_` e têm 57 caracteres:

_Formato_

```bash
# exemplo do formato (esta chave não é válida)
nvx_live_7d3f9a21c48e6b05d7f1a93c2e84b60d5a71f39c8e04b2d6
```

## Como guardar a chave

> 🚫 **A chave dá acesso total à sua conta:** criar cobranças, consultar movimentação e **solicitar saques**. Trate-a como trata a senha do banco.

**Faça:**

- Guarde em variável de ambiente ou cofre de segredos.
- Chame a API **sempre do seu servidor**.
- Use uma chave por aplicação, para poder revogar uma sem derrubar as outras.
- Revogue imediatamente qualquer chave que tenha vazado.

**Nunca faça:**

- Colocar a chave em JavaScript, aplicativo móvel ou qualquer código que roda no dispositivo do cliente — lá ela é pública, por definição.
- Versionar em Git, mesmo em repositório privado.
- Enviar por e-mail, chat ou ticket de suporte. Nossa equipe nunca vai pedir a sua chave.

## Revogar

Em [API Keys](https://novexfinance.com.br/app/api-keys), clique em **Revogar**. O efeito é imediato: a próxima requisição com aquela chave recebe `401` com `revoked_api_key`. Revogar não afeta cobranças já criadas — elas seguem o curso normal.

## Erros de autenticação

| HTTP | Código | O que aconteceu |
| --- | --- | --- |
| `401` | `missing_api_key` | O header `Authorization` não chegou. Verifique se o seu servidor não o está removendo. |
| `401` | `invalid_api_key` | A chave não existe ou está com algum caractere errado. |
| `401` | `revoked_api_key` | A chave foi revogada. Gere uma nova no painel. |
| `403` | `account_inactive` | A conta está suspensa ou bloqueada. Fale com o suporte. |
| `403` | `kyc_required` | A conta existe, mas a verificação de identidade ainda não foi aprovada. Consultas funcionam; cobranças e saques não. |

> ⚠️ **Recebeu `missing_api_key` mesmo enviando o header?** Alguns servidores removem o `Authorization` antes de entregá-lo à aplicação. Teste com `curl -v` a partir de outra máquina para descobrir de que lado o header se perde.


---

Documentação completa: https://novexfinance.com.br/docs/autenticacao
Base da API: https://novexfinance.com.br/api/v1