Autenticação

Todas as requisições de API ao Rafobase requerem autenticação. Este guia cobre como obter e usar suas credenciais de API com segurança.

Chaves de API

Rafobase usa chaves de API para autenticação. Cada chave é escopo de uma única conta de merchant.

As chaves de API são identificadores únicos (UUIDs) gerados por merchant. Cada chave está associada a uma única conta.

Obtendo Sua Chave de API

1. Faça login no Painel do Rafobase
2. Navegue para Configurações → Chaves de API
3. Clique em Gerar Nova Chave
4. Copie e armazene a chave com segurança

Usando Chaves de API

O método principal de autenticação é o cabeçalho X-API-Key. Alternativamente, Authorization: Bearer {key} também é suportado.

curl https://api.rafobase.com/api/v1/member/me?email=test@example.com \
  -H "X-API-Key: $RAFOBASE_API_KEY"

const response = await fetch('https://api.rafobase.com/api/v1/member/me?email=test@example.com', {
  headers: {
    'X-API-Key': process.env.RAFOBASE_API_KEY,
    'Content-Type': 'application/json',
  },
});

import requests
import os

response = requests.get(
    'https://api.rafobase.com/api/v1/member/me',
    params={'email': 'test@example.com'},
    headers={
        'X-API-Key': os.environ['RAFOBASE_API_KEY'],
        'Content-Type': 'application/json',
    }
)

Variáveis de Ambiente

Armazene sua chave de API em variáveis de ambiente:

# .env (nunca faça commit deste arquivo)
RAFOBASE_API_KEY=a1b2c3d4-e5f6-7890-abcd-ef1234567890
RAFOBASE_WEBHOOK_SECRET=f9e8d7c6-b5a4-3210-fedc-ba9876543210

Exemplos de Framework

// Carregue de .env
require('dotenv').config();

const apiKey = process.env.RAFOBASE_API_KEY;

// As variáveis de ambiente do next.config.js são carregadas automaticamente
// Acesse apenas em rotas de API ou componentes de servidor
const apiKey = process.env.RAFOBASE_API_KEY;

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('RAFOBASE_API_KEY')

Verificação de Assinatura de Webhook (Outbound)

Ao receber webhooks enviados pelo Rafobase para seu sistema (outbound), verifique a assinatura para garantir a autenticidade. O cabeçalho utilizado é X-Rafobase-Signature: sha256=xxxxx.

Para mais detalhes, consulte o Guia de Webhooks.

import crypto from 'crypto'

function verifyWebhookSignature(payload, signature, secret) {
  const expected = `sha256=${crypto.createHmac('sha256', secret).update(payload).digest('hex')}`

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

// Em seu manipulador de webhook outbound do Rafobase
app.post('/webhooks/rafobase', (req, res) => {
  const signature = req.headers['x-rafobase-signature']
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.RAFOBASE_WEBHOOK_SECRET
  )

  if (!isValid) {
    return res.status(401).json({ error: 'Assinatura inválida' })
  }

  // Processe o webhook...
})

Rotação de Chave

Periodicamente rotacione suas chaves de API por segurança:

1. Gere uma nova chave
2. Atualize sua aplicação para usar a nova chave
3. Verifique que a nova chave funciona em produção
4. Revogue a chave antiga

Respostas de Erro

Erros de autenticação retornam status 401 Não Autorizado:

{
  "error": {
    "code": "unauthorized",
    "message": "Chave de API inválida ou ausente"
  }
}

Melhores Práticas de Segurança

1. Nunca exponha chaves em código cliente
2. Use variáveis de ambiente - Não codifique as chaves
3. Restrinja permissões de chave - Use chaves de teste para desenvolvimento
4. Monitore o uso de chave - Revise logs de API regularmente
5. Rotacione chaves periodicamente - A cada 90 dias no mínimo
6. Use assinaturas de webhook - Sempre verifique webhooks recebidos

Relacionado

• Guia de Webhooks - Configurando endpoints de webhook
• Referência de API - Documentação completa da API