Autenticação

Todas as requisições às APIs do Felo API Platform exigem autenticação com uma chave de API. Este guia explica como autenticar suas requisições e lidar com problemas comuns de autenticação.

Autenticação com chave de API

A Felo usa autenticação por chave de API em todos os endpoints v2. Sua chave de API identifica sua aplicação e dá acesso aos recursos da plataforma.

Como funciona

1. Você obtém uma chave de API na página de chaves de API do Felo API Platform
2. Você inclui a chave de API no cabeçalho Authorization de cada requisição
3. A plataforma valida sua chave de API e processa a requisição

Formato do cabeçalho

Inclua sua chave de API no cabeçalho Authorization usando o esquema de autenticação Bearer:

Authorization: Bearer YOUR_API_KEY

Exemplo de requisição

curl -X POST https://openapi.felo.ai/v2/chat \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?"}'

Como obter sua chave de API

Para obter sua chave de API:

1. Abra a página de chaves de API do Felo API Platform
2. Entre com sua conta Felo se for solicitado
3. Informe um nome para a chave e clique em Create Key
4. Copie a chave completa quando ela aparecer. Ela é exibida apenas uma vez
5. Guarde a chave com segurança e use-a como FELO_API_KEY

Práticas recomendadas de segurança

1. Guarde as chaves de API com segurança

Não codifique chaves de API diretamente no código-fonte:

# ❌ Bad - API Key exposed in code
api_key = "sk_live_abc123xyz789"

Faça uso de variáveis de ambiente ou configuração segura:

# ✅ Good - API Key from environment
import os
api_key = os.environ.get('FELO_API_KEY')

2. Use variáveis de ambiente

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

Linux/macOS:

export FELO_API_KEY="sk_live_abc123xyz789"

Windows (Prompt de Comando):

set FELO_API_KEY=sk_live_abc123xyz789

Windows (PowerShell):

$env:FELO_API_KEY="sk_live_abc123xyz789"

3. Rotacione as chaves regularmente

Gere periodicamente novas chaves de API e revogue as antigas para minimizar riscos de segurança.

4. Use chaves diferentes para ambientes diferentes

Crie chaves de API separadas para os ambientes de desenvolvimento, homologação e produção.

5. Nunca exponha chaves em código do lado do cliente

Chaves de API devem ser usadas apenas em código do lado do servidor. Nunca as inclua em:

• Código JavaScript de frontend
• Código-fonte de app mobile
• Repositórios públicos
• Arquivos de configuração do lado do cliente

Erros de autenticação

Para ver o envelope completo de erros, os cabeçalhos de limite de requisições e a política de novas tentativas, consulte Erros, limites e novas tentativas.

Códigos de erro comuns

Uma requisição rejeitada retorna o status da chave em message:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key is required",
  "request_id": "..."
}

status é o código de status HTTP. Uma chave revogada informa API Key has been revoked (keyPrefix=...). Decida com base no status HTTP e em code, não no texto exato de message.

Solução de problemas

Se a autenticação falhar:

1. Verifique se o cabeçalho é exatamente Authorization: Bearer YOUR_API_KEY.
2. Confirme que a chave não foi revogada na página de chaves de API.
3. Confirme que o ambiente está usando a chave que você espera.
4. Gere uma nova chave se a antiga foi excluída ou rotacionada. A chave completa só é exibida uma vez, na criação.

Para uma lista de verificação que começa pelos sintomas e cobre a autenticação e o restante da plataforma, consulte Solução de problemas.

Exemplo: depurar a autenticação

import requests

url = "https://openapi.felo.ai/v2/chat"
api_key = "YOUR_API_KEY"

# Correct format
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={"query": "test"})

if response.status_code == 401:
    error = response.json()
    print(f"Authentication failed: {error['code']}")
    print(f"Message: {error['message']}")
    print(f"Request ID: {error['request_id']}")
else:
    print("Authentication successful!")

Limites de requisições

Os limites de requisições valem por endpoint, não globalmente por chave de API. No momento, apenas `/v2/chat` aplica limites; usuários com uma assinatura Felo paga efetiva estão isentos. Os demais endpoints /v2/** não têm limites de requisições aplicados.

Uma resposta 429 inclui os cabeçalhos X-RateLimit-* e Retry-After. Leia sempre os limites efetivos nos cabeçalhos da resposta, não na documentação.

Para ver as dimensões completas dos limites, os cabeçalhos e a política de novas tentativas, consulte Erros, limites e novas tentativas.

Precisa de ajuda?

Se você está enfrentando problemas de autenticação:

1. Revise este guia com atenção
2. Consulte o guia de Primeiros passos
3. Verifique sua chave de API na página de chaves de API
4. Fale com o suporte em [email protected] informando seu request ID

Próximos passos

• Guia de primeiros passos - Aprenda a fazer sua primeira chamada à API
• Referência da Chat API - Explore a documentação da Chat API