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

# Autenticacao

> Como autenticar requisicoes na API TurbofyPay com client credentials e assinatura HMAC em operacoes financeiras sensiveis.

<div className="turbofy-hero">
  <span className="turbofy-eyebrow">Seguranca de integracao</span>
  <h1>Autentique sua API sem ambiguidade</h1>

  <p className="turbofy-lead">
    Para integracao publica, use `x-client-id` e `x-client-secret`. Em operacoes
    financeiras sensiveis como payouts, checkout P0 e download de comprovantes,
    adicione assinatura HMAC com timestamp para proteger transacoes sensiveis.
  </p>

  <div className="turbofy-hero-actions">
    <a href="/reference/payouts/criar-lote-payouts">Ver endpoint de payouts</a>
    <a href="/integracao/api-overview">Ver glossario da API</a>
  </div>
</div>

## Chaves de API

<div className="turbofy-note">
  <strong>Importante:</strong> suas credenciais identificam a conta e autorizam
  cada requisicao. Configure apenas no backend e nunca exponha o secret no
  frontend, app mobile ou logs.
</div>

Headers obrigatorios para toda API publica:

* `x-client-id`
* `x-client-secret`

## Fluxo basico

```bash theme={null}
POST /sellers/pix
x-client-id: <client-id>
x-client-secret: <client-secret>
Idempotency-Key: pedido-123
```

## Assinatura HMAC para operacoes financeiras sensiveis

Rotas financeiras sensiveis podem exigir tambem:

* `x-turbofy-timestamp`
* `x-turbofy-signature`

No Checkout P0 (`POST /v1/checkouts`), a politica real atual do backend e:

* em `production`: assinatura obrigatoria;
* fora de `production`: assinatura pode ser opcional.

### Como a assinatura e calculada

Assine com HMAC SHA-256 a string abaixo:

```text theme={null}
{timestamp}.{method}.{path}.{body}
```

* `timestamp`: mesmo valor enviado em `x-turbofy-timestamp`
* `method`: `GET`, `POST`, etc. sempre em maiusculo
* `path`: somente caminho da rota (sem dominio e sem query string)
* `body`: JSON bruto exatamente como enviado (em `GET`, use vazio)

<img src="https://mintcdn.com/turbofypay/PV8PQGFRC5_DV7l4/images/enterprise/hmac-signature-flow.png?fit=max&auto=format&n=PV8PQGFRC5_DV7l4&q=85&s=385028bb76e67acc3c828f62430a1c30" alt="Diagrama da assinatura HMAC usando timestamp, metodo, path e body para gerar os headers x-turbofy-timestamp e x-turbofy-signature." width="1586" height="992" data-path="images/enterprise/hmac-signature-flow.png" />

*O payload assinado deve reproduzir exatamente a requisicao enviada. Qualquer mudanca em metodo, path, body ou timestamp exige nova assinatura.*

### Regra critica

Recalcule a assinatura em **toda requisicao**. Se mudar metodo, path, body ou timestamp, a assinatura antiga deixa de ser valida.

## Exemplo Bash (Linux/macOS/Git Bash)

```bash theme={null}
CLIENT_SECRET="SEU_CLIENT_SECRET"
TIMESTAMP=$(date +%s%3N)
METHOD="POST"
PATH_ONLY="/v1/payouts/batches"
BODY='{"idempotencyKey":"folha-001","description":"Folha semanal","items":[]}'

PAYLOAD="$TIMESTAMP.$METHOD.$PATH_ONLY.$BODY"

SIGNATURE=$(printf "%s" "$PAYLOAD" \
  | openssl dgst -sha256 -hmac "$CLIENT_SECRET" -hex \
  | sed 's/^.* //')

echo "$TIMESTAMP"
echo "$SIGNATURE"
```

## Exemplo PowerShell (Windows)

```powershell theme={null}
$clientSecret = "SEU_CLIENT_SECRET"
$timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds().ToString()
$method = "POST"
$pathOnly = "/v1/payouts/batches"
$body = '{"idempotencyKey":"folha-001","description":"Folha semanal","items":[]}'

$payload = "$timestamp.$method.$pathOnly.$body"

$hmac = [System.Security.Cryptography.HMACSHA256]::new(
  [System.Text.Encoding]::UTF8.GetBytes($clientSecret)
)
$signatureBytes = $hmac.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($payload))
$signature = -join ($signatureBytes | ForEach-Object { $_.ToString("x2") })

Write-Output $timestamp
Write-Output $signature
```

## Erros comuns de assinatura

* `401 INVALID_SIGNATURE`: assinatura ausente, invalida ou expirada.
* Metodo assinado diferente do metodo enviado (`GET` vs `POST`).
* Path assinado com dominio ou query string.
* Body assinado diferente do body efetivamente enviado.
* Timestamp fora da janela de validacao.

## Boas praticas

* Gere assinatura imediatamente antes do envio.
* Nao reutilize assinatura entre requisicoes.
* Mantenha relogio do servidor sincronizado (NTP).
* Nunca registre `x-client-secret` em logs.
* Use `Idempotency-Key` em operacoes de escrita.

## Proximos passos

1. Teste uma chamada real em [Criar cobranca PIX](/reference/cobranca-pix/criar-cobranca-pix).
2. Em checkout P0, valide [Criar checkout](/reference/checkouts/criar-checkout).
3. Em payouts, valide assinatura em [Criar lote de payouts](/reference/payouts/criar-lote-payouts).
4. Em comprovantes, valide assinatura em [Baixar comprovante de transacao](/reference/comprovantes/baixar-comprovante-transacao).