voltarAthelium · docs
Suporte técnico
Documentação

Autenticação

Toda chamada exige uma API key. A key identifica a empresa e determina a quais nichos e skills você tem acesso.

Como conseguir uma API key

API keys são geradas pela curadoria. Após o onboarding, você recebe a key por canal seguro (e não verá ela inteira de novo — só o prefixo, no portal da sua empresa).

Precisa de uma key nova ou rotacionar? Solicite à curadoria pelo seu canal de contato.

Três formas de enviar a key

Em ordem de recomendação — escolha a primeira que sua ferramenta suporta:

1. Header Bearer (recomendado)

http
Authorization: Bearer <sua_api_key>

Padrão da indústria. Use sempre que possível.

2. Header X-API-Key

http
X-API-Key: <sua_api_key>

Alternativa quando a ferramenta não aceita header Authorization — comum em alguns conectores corporativos antigos.

3. Query param (último recurso)

http
?api_key=<sua_api_key>

Use só quando a ferramenta não permite headers customizados (raro). A key aparece em logs de servidor e proxy — risco aumentado de exposição.

Boas práticas

  • Nunca commite a key. Sempre via variável de ambiente ou secret manager.
  • Use uma key por ambiente. Dev, staging e produção devem ter keys distintas. Facilita revogação cirúrgica em caso de incidente.
  • Rotacione periodicamente. Trimestral é razoável. Se desconfiar de exposição, rotacione na hora.
  • Não exponha em frontend. Toda chamada deve sair de backend ou edge function — nunca direto do navegador.

Exemplo: lendo a key de variável de ambiente

.env
# .env (nunca commitar)
SKILLS_API_KEY=<sua_api_key>
SKILLS_GATEWAY=https://gateway.athelium.com.br

Python:

compose.pypython
import os
import httpx

API_KEY = os.environ["SKILLS_API_KEY"]
GATEWAY = os.environ["SKILLS_GATEWAY"]

async with httpx.AsyncClient(timeout=60) as client:
    r = await client.post(
        f"{GATEWAY}/api/v1/compose",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"intent": "..."},
    )

O que acontece quando a key é inválida

  • 401 missing api key — header ou query param ausente.
  • 401 invalid api key — key foi revogada, expirou ou nunca existiu. Solicite uma nova.
  • 403 tenant mismatch — a key pertence a uma empresa, mas a chamada referencia outra (defesa multi-tenant). Algum parâmetro do body está errado.

Próximos passos