Autenticação

A Toktus API usa API Keys para autenticar todas as requisições. Cada conta tem uma chave única (formato tk_...) que identifica seu cliente e suas permissões.

Fluxo de autenticação

graph LR
    A[Criar conta no painel] --> B[Copiar API Key]
    B --> C[Enviar no header x-api-key]
    C --> D[Requisição autenticada]

1. Obter sua API Key

A criação de conta acontece exclusivamente pelo painel da Toktus, não pela API. O signup público da API foi removido para evitar criação automatizada de contas por bots e manter o onboarding centralizado.

1. Cadastre-se em app.toktus.com

   Acesse app.toktus.com, faça signup com seu e-mail e confirme via link enviado na sua caixa de entrada.

2. Acesse Configurações

   Após entrar no painel, clique em Configurações no menu lateral.

3. Gere sua API Key

   Na seção API, clique em Gerar nova chave. A chave (formato tk_...) é exibida uma única vez — copie e armazene em local seguro antes de fechar a tela.

[!WARNING]
A API Key tem permissão total sobre sua conta (criar cobranças, estornar, alterar configurações). Trate com o mesmo cuidado que daria a uma senha de banco.

2. Configurar a conta (opcional, mas recomendado)

Com a API Key em mãos, você pode definir comportamentos padrão antes de processar pagamentos. Todas as configurações são feitas via um único endpoint:

curl -X PATCH https://api.toktus.com/api/v1/clients/settings \
  -H "x-api-key: tk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryGateway": "pagarme",
    "gatewayFallbacks": ["asaas", "stripe"],
    "compatibilityMode": null,
    "responseFormat": "normalized"
  }'

[!TIP]
Configurar primaryGateway é especialmente útil se você usa sempre o mesmo gateway — elimina o campo gateway de todas as suas chamadas. Veja Configurações da conta para detalhes.

3. Usar a API Key

Inclua sua API Key no header x-api-key em todas as requisições:

curl -X GET https://api.toktus.com/api/v1/credentials \
  -H "x-api-key: tk_a1b2c3d4e5f6789abcdef..."

Exemplos por linguagem

Consultar dados da sua conta

Para inspecionar os dados da conta autenticada (incluindo URLs de webhook prontas), use GET /api/v1/clients/me:

curl https://api.toktus.com/api/v1/clients/me \
  -H "x-api-key: tk_SUA_CHAVE"

A resposta inclui as URLs específicas que você deve cadastrar em cada gateway para receber notificações:

{
  "success": true,
  "data": {
    "id": "550e8400-...",
    "name": "Minha Empresa",
    "email": "[email protected]",
    "webhookToken": "wh_...",
    "webhookUrls": {
      "stripe": "https://api.toktus.com/api/v1/webhooks/stripe/wh_...",
      "pagarme": "https://api.toktus.com/api/v1/webhooks/pagarme/wh_...",
      "asaas": "https://api.toktus.com/api/v1/webhooks/asaas/wh_...",
      "mercadopago": "https://api.toktus.com/api/v1/webhooks/mercadopago/wh_...",
      "pagseguro": "https://api.toktus.com/api/v1/webhooks/pagseguro/wh_..."
    }
  }
}

[!NOTE]
A API Key nunca é retornada por nenhum endpoint após a geração inicial. Se você perder a chave, gere outra no painel — a anterior fica automaticamente revogada.

Segurança da API Key

Faça

• Armazene em variáveis de ambiente (.env, não commite no Git)
• Use cofres de segredos em produção (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
• Rotacione periodicamente — gere uma nova chave e revogue a antiga
• Monitore uso suspeito (IPs desconhecidos, volumes anormais)
• Use HTTPS sempre, nunca HTTP

Não faça

• Commitar no Git ou repositórios públicos
• Hardcodear no código-fonte
• Expor em requisições client-side (JavaScript no navegador)
• Compartilhar via e-mail, chat ou canais não criptografados
• Registrar em logs ou sistemas de monitoramento em texto claro
• Incluir em URLs ou query parameters

Exemplo: armazenando com segurança

.env (local)

    # .env (adicione ao .gitignore!)
    TOKTUS_API_KEY=tk_a1b2c3d4e5f6789abcdef...
    ```

## Docker Compose

```yaml
    version: '3.8'
    services:
      api:
        image: sua-api:latest
        environment:
          - TOKTUS_API_KEY=${TOKTUS_API_KEY}
        env_file:
          - .env.production
    ```

## Kubernetes

```bash
    kubectl create secret generic toktus-credentials \
      --from-literal=api-key='tk_a1b2c3d4e5f6789abcdef...'
    ```

    ```yaml
    apiVersion: v1
    kind: Pod
    metadata:
      name: sua-api
    spec:
      containers:
      - name: app
        image: sua-api:latest
        env:
        - name: TOKTUS_API_KEY
          valueFrom:
            secretKeyRef:
              name: toktus-credentials
              key: api-key
    ```

## Endpoints públicos (sem autenticação)

Apenas os webhooks dispensam o header `x-api-key`:

| Endpoint | Motivo |
|----------|--------|
| `POST /api/v1/webhooks/*` | Webhooks recebidos dos gateways. A autenticidade é validada pela assinatura criptográfica enviada pelo gateway de origem. |

**Todos os demais endpoints** exigem o header `x-api-key`.

## Erros de autenticação

### 401 MISSING_API_KEY

```json
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Header x-api-key is required"
  }
}

Solução: adicione o header x-api-key: tk_sua_chave.

401 INVALID_API_KEY

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Causas possíveis:

• Chave digitada incorretamente
• Chave revogada (você gerou outra e essa virou inválida automaticamente)
• Chave de uma conta diferente da que você espera estar usando

403 CLIENT_INACTIVE

{
  "success": false,
  "error": {
    "code": "CLIENT_INACTIVE",
    "message": "Your account has been deactivated"
  }
}

Solução: entre em contato com o suporte em [email protected] para reativar.

Rate Limiting

Para proteger a API, aplicamos limites de taxa:

Resposta HTTP 429:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido. Aguarde 45 segundos antes de tentar novamente."
  }
}

Headers incluídos:

• Retry-After: 45 — segundos até poder tentar novamente
• X-RateLimit-Limit: 100 — limite total
• X-RateLimit-Remaining: 0 — requisições restantes
• X-RateLimit-Reset: 60 — segundos até reset da janela

Próximos passos

• Credenciais — Cadastrar as chaves de cada gateway de pagamento
• Configurações da conta — Gateway padrão, fallbacks, modo de compatibilidade e formato de resposta
• Clientes e assinaturas — Criar seu primeiro cliente ou assinatura
• Erros — Referência completa de códigos de erro