Autenticação e chaves de API

A API da Discuse autentica todas as solicitações com uma chave de API. Envie-a no cabeçalho de solicitação X-API-Key (ou como um campo api_key no corpo JSON). As chaves começam com o prefixo disc_, são vinculadas a um único projeto e são exibidas por completo apenas uma vez, no momento da criação. Este guia explica como obtê-las, usá-las, protegê-las e rotacioná-las.

Como funciona a autenticação da Discuse?

Toda chamada à API deve incluir uma chave de API válida. A Discuse a utiliza para:

Acompanhar o uso em relação à cota do seu projeto
Aplicar limitação de taxa por chave para evitar abusos
Associar as solicitações ao projeto correto e às suas configurações
Controlar o acesso aos recursos da sua conta

Como obter sua chave de API

Etapa 1: Crie uma conta

Se ainda não tiver uma, crie uma conta da Discuse em discuse.com. Você pode começar pelo plano Basic gratuito, que inclui uma franquia mensal de solicitações de API, além de acesso a verificações de texto, spam, idioma e imagem. Consulte a página de preços para ver os limites atuais de cada plano.

Etapa 2: Acesse o painel

Depois de fazer login, acesse seu painel. Procure a seção "API Keys" ou "Developer" no menu de navegação.

Etapa 3: Gere uma nova chave

Clique em "Create New API Key" e, opcionalmente, forneça um nome ou uma descrição para a chave. Isso ajuda a identificar a finalidade de cada chave caso você crie várias.

Sua nova chave de API será exibida apenas uma vez. Copie-a imediatamente e armazene-a com segurança — você não poderá ver a chave completa novamente.

Como usar sua chave de API

Inclua sua chave de API no cabeçalho X-API-Key de todas as solicitações:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

Como alternativa, você pode passar a chave como um campo api_key dentro do corpo JSON em vez do cabeçalho — o cabeçalho é preferível para que a chave nunca acabe em logs do corpo da solicitação.

Exemplo em JavaScript

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

Exemplo em Python

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

Boas práticas de segurança para chaves de API

Nunca exponha chaves em código do lado do cliente

Chaves de API nunca devem ser incluídas em JavaScript executado no navegador. Código do lado do cliente fica visível para qualquer pessoa que visualize o código-fonte da sua página.

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

Use variáveis de ambiente

Armazene chaves de API em variáveis de ambiente, não na sua base de código:

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

Rotacione as chaves regularmente

Rotacione periodicamente suas chaves de API, especialmente se suspeitar que elas possam ter sido comprometidas:

Gere uma nova chave de API
Atualize sua aplicação para usar a nova chave
Verifique se tudo funciona corretamente
Revogue a chave antiga

Observação: uma chave revogada pode continuar utilizável por até cerca de 5 minutos porque chaves validadas ficam em cache. Planeje as rotações considerando essa breve sobreposição, em vez de esperar uma troca instantânea.

Use chaves separadas para ambientes diferentes

Crie chaves de API diferentes para desenvolvimento, staging e produção:

Ambiente	Finalidade da chave
Desenvolvimento	Testes e desenvolvimento local
Staging	Testes de pré-produção
Produção	Tráfego da aplicação em produção

Isso permite revogar uma chave comprometida sem afetar outros ambientes.

Como funciona a limitação de taxa?

A limitação de taxa é por chave de API, não por plano. Cada chave tem um limite de solicitações por minuto (RPM) definido no momento da criação; se você não especificar um, o padrão será 60 solicitações por minuto. Chaves diferentes na mesma conta podem ter limites diferentes, permitindo que você atribua um RPM mais alto a um serviço de alto volume do que a uma integração pontual.

Quando uma chave excede seu limite de RPM, a solicitação falha com o status HTTP 429 Too Many Requests, cujo message informa que o limite de taxa foi excedido. Os contadores de limite de taxa são redefinidos em uma janela móvel de um minuto.

Como lidar com limites de taxa

Aguarde e tente novamente em caso de 429 (e também em erros transitórios 5xx). Como a janela é de um minuto, uma espera exponencial que começa em torno de um segundo e aumenta funciona bem:

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

Quais respostas de erro posso receber?

Situação	Status HTTP
Solicitação malformada (conteúdo vazio, texto com mais de 10.000 caracteres, URLs em excesso)	validação de solicitação `400`
Chave de API ausente ou inválida	`401`
Limite de taxa excedido para a chave	`429`
Cota do período de cobrança esgotada	`200` com uma `message` e `usage` (não é um status de erro)

O esgotamento da cota não é intencionalmente um erro HTTP: a resposta de /api/v2/check ainda retorna 200 com has_violations: false, uma message descrevendo a cota esgotada e um objeto usage mostrando api_requests_remaining: 0. Inspecione esses campos em vez de depender de um código de status. Falhas de autenticação retornam 401, limites de taxa retornam 429 e falhas de validação da solicitação retornam 400. Consulte a referência Códigos de erro e resposta para ver a lista completa.

Como gerenciar várias chaves

Para equipes maiores ou aplicações complexas, você pode precisar de várias chaves de API:

Casos de uso para várias chaves

Chaves por ambiente: chaves separadas para desenvolvimento, staging e produção
Chaves por serviço: chaves diferentes para microserviços diferentes
Chaves por equipe: isole o uso por equipe para cobrança interna
Chaves temporárias: chaves de curta duração para prestadores de serviço ou integrações

Boas práticas de gerenciamento de chaves

Dê nomes descritivos às chaves: "Production - User Service", "Staging - Backend"
Documente o uso das chaves: mantenha registros de qual chave é usada em cada lugar
Configure alertas: monitore padrões de uso incomuns
Faça auditorias regulares: revise e remova chaves não utilizadas trimestralmente

Próximos passos

Guia de início rápido - Faça sua primeira chamada à API
Análise de texto - Saiba mais sobre detecção de sentimento
Escalabilidade da moderação de conteúdo - Padrões de implementação para alto volume