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

# Autenticação

> Entenda como funcionam as chaves da TroqPay e como usá-las com segurança.

# Autenticação

Toda chamada para a API da TroqPay precisa de uma chave válida.

Sem ela, a requisição não passa.

<Tip>
  A chave identifica sua conta e também define se a requisição está em teste ou em produção.
</Tip>

## O que você precisa saber

<CardGroup cols={2}>
  <Card title="Bearer token">
    Toda requisição autenticada usa o header `Authorization: Bearer ...`.
  </Card>

  <Card title="Mesmo endpoint para os dois ambientes">
    Você continua usando `https://api.troqpay.com`. O ambiente muda de acordo com a chave.
  </Card>

  <Card title="Chaves de teste">
    Use prefixo `trq_test_` para homologação e validação do fluxo.
  </Card>

  <Card title="Chaves de produção">
    Use prefixo `trq_live_` para cobranças reais.
  </Card>
</CardGroup>

## Header obrigatório

```bash theme={null}
Authorization: Bearer trq_test_xxxxxxxxx
```

Exemplo:

```bash theme={null}
curl https://api.troqpay.com/v1/checkouts \
  -H "Authorization: Bearer trq_test_xxxxxxxxx"
```

## URL-base

```text theme={null}
https://api.troqpay.com
```

Isso vale para teste e produção.

## Acesso a produção

Chaves `trq_live_` só funcionam quando sua conta está marcada como `APPROVED` para produção. Antes disso, chamadas de produção retornam `403 forbidden` com uma mensagem relacionada ao recurso chamado.

Os quatro estados possíveis da sua conta são:

| Estado           | O que significa                                         |
| ---------------- | ------------------------------------------------------- |
| `NOT_REQUESTED`  | Você ainda não pediu acesso à produção                  |
| `PENDING_REVIEW` | Você pediu, e o time da TroqPay está analisando         |
| `APPROVED`       | Você pode usar `trq_live_` em todas as rotas suportadas |
| `REJECTED`       | A TroqPay rejeitou; veja o motivo no app                |

<Info>
  O bloqueio se aplica a `POST /v1/checkouts`, `GET /v1/balance` e saques em produção. A consulta `GET /v1/checkouts/{checkoutId}` continua funcionando mesmo em contas que não estão `APPROVED`, desde que a chave tenha permissão de leitura de checkout.
</Info>

Veja [Produção](/production) para o caminho de aprovação.

## Permissões da chave

Nem toda chave pode chamar todos os recursos.

Uma chave server-side pode receber permissões separadas para:

| Permissão             | Recurso                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------- |
| `CHECKOUT:CREATE`     | criar checkouts em `POST /v1/checkouts`                                                       |
| `CHECKOUT:READ`       | consultar checkouts em `GET /v1/checkouts/{checkoutId}`                                       |
| `BALANCE:READ`        | consultar saldo em `GET /v1/balance`                                                          |
| `WITHDRAWAL:CREATE`   | solicitar saques em `POST /v1/withdrawals`                                                    |
| `WITHDRAWAL:READ`     | consultar saques em `GET /v1/withdrawals/{withdrawalId}`                                      |
| `PAYMENT_LINK:CREATE` | criar links de pagamento em `POST /v1/payment-links`                                          |
| `PAYMENT_LINK:READ`   | listar e consultar links em `GET /v1/payment-links` e `GET /v1/payment-links/{paymentLinkId}` |

No fluxo comum, a chave de integração de checkout já vem com criação/leitura de checkout e leitura de saldo. Para criar ou consultar saques pela API, a chave precisa ter permissão de saque.

<Info>
  As permissões `PAYMENT_LINK:CREATE` e `PAYMENT_LINK:READ` são emitidas por padrão em **toda chave nova** (teste e produção). Chaves antigas, geradas antes dessas permissões existirem, **não as têm** e recebem `403 api_key_scope_forbidden` nas rotas de payment-links até serem reemitidas.
</Info>

<Warning>
  Trate uma chave com permissão de saque como segredo de alto impacto. Ela deve ficar somente no backend e nunca em código de front-end, app mobile, logs públicos ou repositórios.
</Warning>

## Idempotência

Quando você cria um checkout, mande também o header `Idempotency-Key`. Para criar um saque pela API, esse header é obrigatório.

```bash theme={null}
Idempotency-Key: order_1001
```

A API normaliza o corpo da requisição com uma serialização JSON estável (chaves em ordem alfabética). Isso significa que reordenar campos no JSON conta como o **mesmo** corpo. Mudar, adicionar ou remover qualquer campo conta como um corpo **diferente** e vira `409 idempotency_conflict`.

Outros pontos importantes:

* a chave não tem prazo de validade — ela fica associada ao recurso para sempre
* a primeira criação devolve `201 Created`. Uma reentrega idempotente (mesma chave, mesmo corpo) devolve `200 OK` com o recurso já existente
* em checkouts, a API trima o valor; uma string vazia depois do trim é tratada como se você não tivesse enviado a chave
* em saques, não enviar uma chave válida retorna `400 idempotency_key_required`

<Tip>
  Use um identificador estável do seu sistema (ex.: `order_1001`, `subscription_42_invoice_3`) como `Idempotency-Key`. Isso evita colisões e dá deduplicação útil mesmo em janelas longas.
</Tip>

## Request-Id

Toda resposta da API inclui o header `Request-Id` no formato `req_<24 hex>`.

Você pode também enviar seu próprio identificador na requisição em `Request-Id` ou `X-Request-Id`. Quando você manda, a API ecoa o mesmo valor de volta. Quando você não manda, ela gera um.

Use esse campo para correlacionar logs do seu sistema com o que aconteceu na TroqPay quando precisar abrir um suporte.

## Boas práticas

* guarde suas chaves em variáveis de ambiente
* nunca exponha segredos no front-end
* use chaves separadas para teste e produção
* revogue a chave imediatamente em caso de suspeita de vazamento

## Onde isso costuma ser configurado

No fluxo mais comum, você vai:

1. gerar a chave no `app.troqpay.com`
2. salvar o segredo no seu gerenciador de segredos
3. usar a chave no backend
4. manter teste e produção em variáveis separadas

## Erros comuns

| HTTP  | Código                           | O que normalmente significa                                                                                                          |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `401` | `unauthorized`                   | Chave ausente, mal formatada, inválida ou revogada. A API sempre devolve `unauthorized` em 401 — confira a `message` para o detalhe. |
| `403` | `forbidden`                      | Sua conta ainda não tem acesso a produção, ou a chave não tem permissão para o recurso.                                              |
| `403` | `api_key_scope_forbidden`        | A chave não tem permissão para o recurso chamado.                                                                                    |
| `403` | `test_withdrawals_not_supported` | Saques só estão disponíveis em produção.                                                                                             |
| `429` | `rate_limit_exceeded`            | Limite de requisições excedido. Respeite o header `Retry-After` e faça retry com backoff.                                            |

## Próximos passos

* [Testar no sandbox](/sandbox)
* [Criar seu primeiro checkout](/quickstart)
* [Entender os erros da API](/flows/errors)

## Precisa de ajuda para seguir?

<CardGroup cols={3}>
  <Card title="Fazer o Quickstart" href="/quickstart">
    Use uma `trq_test_` para validar seu primeiro checkout sem depender de produção.
  </Card>

  <Card title="Revisar o sandbox" href="/sandbox">
    Confirme como separar os ambientes e o que observar nas respostas de teste.
  </Card>

  <Card title="Abrir o app" href="https://app.troqpay.com">
    Gere ou revise suas chaves diretamente no app da TroqPay.
  </Card>
</CardGroup>