Pular para o conteúdo principal

Autenticação e API Keys

🔐 Segurança primeiro: Como proteger suas chamadas à API e evitar duplicidades

Toda requisição à API Notifica precisa de autenticação. Este guia cobre:

  • Como funcionam as API keys
  • Criar, listar e revogar chaves
  • Chaves de idempotência
  • Boas práticas de segurança

Como funciona a autenticação​

A Notifica usa Bearer Token no header Authorization:

Authorization: Bearer nk_live_xxxxx

Formato das chaves:

  • nk_live_ — Chave de produção (envia notificações reais)
  • nk_test_ — Chave de sandbox (para desenvolvimento)

Criando API Keys​

Via Dashboard (recomendado)​

  1. Acesse Configurações → API Keys
  2. Clique em Nova API Key
  3. Defina:
    • Nome: identificação (ex: "Backend Produção")
    • Permissões: leitura, escrita ou ambas
    • IPs permitidos (opcional): whitelist de IPs
  4. Copie a chave imediatamente — ela não aparece novamente!

Via API​

curl -X POST https://app.usenotifica.com.br/api-keys \
  -H "Authorization: Bearer nk_live_sua_chave_atual" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend - Serviço de Cobrança",
    "permissions": ["write", "read"],
    "allowed_ips": ["201.45.123.0/24"]
  }'

Resposta:

{
  "id": "key_abc123",
  "name": "Backend - Serviço de Cobrança",
  "key": "nk_live_nova_chave_aqui_somente_uma_vez",
  "permissions": ["write", "read"],
  "allowed_ips": ["201.45.123.0/24"],
  "created_at": "2024-01-15T14:30:00Z",
  "last_used_at": null
}

Listando API Keys​

curl https://app.usenotifica.com.br/api-keys \
  -H "Authorization: Bearer nk_live_sua_chave"

Resposta:

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Backend Produção",
      "permissions": ["write", "read"],
      "created_at": "2024-01-10T09:00:00Z",
      "last_used_at": "2024-01-15T16:45:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1
  }
}

⚠️ Atenção: A chave real (key) nunca é retornada na listagem por segurança.

Revogando API Keys​

Se uma chave for comprometida ou não for mais necessária:

curl -X DELETE https://app.usenotifica.com.br/api-keys/key_abc123 \
  -H "Authorization: Bearer nk_live_sua_chave"

✅ Revogação imediata: Todas as requisições com essa chave falharão instantaneamente.

Idempotência (Evite duplicatas)​

O header Idempotency-Key garante que a mesma requisição POST não execute duas vezes.

Quando usar:

  • Envio de notificações críticas (faturas, alertas)
  • Retry automático em caso de timeout
  • Webhooks que podem disparar múltiplas vezes

Como funciona​

# Primeira requisição
IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST https://app.usenotifica.com.br/v1/notifications \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{...}'
# → 201 Created, notificação enviada

# Segunda requisição (mesmo idempotency key)
curl -X POST https://app.usenotifica.com.br/v1/notifications \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{...}'
# → 200 OK, retorna a mesma resposta sem criar duplicata

Implementação em código​

Node.js:

const { randomUUID } = require('crypto');

async function enviarComIdempotencia(payload) {
  const idempotencyKey = randomUUID(); // ou use ID do seu banco
  
  return fetch('https://app.usenotifica.com.br/v1/notifications', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });
}

Python:

import uuid

idempotency_key = str(uuid.uuid4())
# ou use: idempotency_key = f"payment-{payment_id}"

response = requests.post(
    f'{BASE_URL}/notifications',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Idempotency-Key': idempotency_key
    },
    json=payload
)

Dicas:

  • Reutilize IDs do seu sistema (ex: payment-12345)
  • Chaves ficam em cache por 24 horas
  • Apenas POST requests suportam idempotência

Segurança: Boas Práticas​

✅ Faça​

  • Use variáveis de ambiente para API keys
  • Crie chaves separadas por ambiente (dev/staging/prod)
  • Restrinja por IP quando possível
  • Use idempotency keys em operações críticas
  • Rotacione chaves periodicamente (a cada 90 dias)

❌ Nunca​

  • Commite chaves em repositórios
  • Compartilhe chaves entre equipes
  • Use chaves de produção em localhost
  • Logue chaves em sistemas de monitoramento

Código completo: Segurança na prática​

Node.js (com dotenv)​

require('dotenv').config();

const API_KEY = process.env.NOTIFICA_API_KEY;
if (!API_KEY) {
  throw new Error('NOTIFICA_API_KEY não configurada');
}

async function notificaRequest(endpoint, options = {}) {
  const url = `https://app.usenotifica.com.br/v1${endpoint}`;
  
  const response = await fetch(url, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  
  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.message || `HTTP ${response.status}`);
  }
  
  return response.json();
}

// Uso
notificaRequest('/notifications', {
  method: 'POST',
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({ to: { email: '[email protected]' }, ... })
});

Python (com python-dotenv)​

import os
from dotenv import load_dotenv
import requests

load_dotenv()

API_KEY = os.getenv('NOTIFICA_API_KEY')
if not API_KEY:
    raise ValueError('NOTIFICA_API_KEY não configurada')

class NotificaClient:
    BASE_URL = 'https://app.usenotifica.com.br/v1'
    
    def __init__(self, api_key):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        })
    
    def request(self, method, endpoint, **kwargs):
        url = f'{self.BASE_URL}{endpoint}'
        response = self.session.request(method, url, **kwargs)
        response.raise_for_status()
        return response.json()
    
    def send_notification(self, payload, idempotency_key=None):
        headers = {}
        if idempotency_key:
            headers['Idempotency-Key'] = idempotency_key
        
        return self.request('POST', '/notifications', 
                          headers=headers, json=payload)

# Uso
client = NotificaClient(API_KEY)
client.send_notification(
    payload={'to': {'email': '[email protected]'}, ...},
    idempotency_key=str(uuid.uuid4())
)

Variáveis de ambiente (.env)​

# .env (nunca commit!)
NOTIFICA_API_KEY=nk_live_sua_chave_secreta
NOTIFICA_API_KEY_TEST=nk_test_chave_sandbox

# Opcional: para webhook verification
NOTIFICA_WEBHOOK_SECRET=whsec_xxx

Troubleshooting​

401 Unauthorized​

{"error": "invalid_api_key", "message": "API key inválida ou revogada"}

Causas comuns:

  • Chave copiada incompleta (faltou nk_live_)
  • Chave foi revogada
  • Header mal formatado (esqueceu "Bearer")

403 Forbidden​

{"error": "insufficient_permissions", "message": "Chave só tem permissão de leitura"}

Causas comuns:

  • Chave criada apenas com permissão read
  • IP não está na whitelist configurada

FAQ​

Q: Posso ter múltiplas chaves ativas?
A: Sim! Recomendamos criar chaves separadas por serviço/equipe.

Q: As chaves expiram?
A: Não automaticamente. Revogue manualmente quando não for mais necessária.

Q: Como descubro qual chave fez uma requisição?
A: No dashboard, em Logs de API, você vê a chave ID (últimos 4 caracteres).

Q: Posso restringir chaves por endpoint?
A: Por enquanto, apenas por permissão (read/write) e IP. Granularidade por endpoint em breve!

Próximo passo​

Agora que você domina autenticação, aprenda a gerenciar Assinantes — a base de qualquer sistema de notificações.