Autenticação
A FabHub suporta dois modelos: chaves de API para automação detida pelo tenant, e OAuth para aplicações parceiras aprovadas que atuam em nome de um tenant.
Chaves de API
Envie a chave em cada pedido com o cabeçalho X-API-Key (a forma Authorization: Bearer <key> também é aceite):
curl https://api.fabhub.app/v1/items \
-H "X-API-Key: $FABHUB_API_KEY"
- Prefixos:
pk_test_*para não produção,pk_live_*para produção. - Gestão: crie, atribua scopes e revogue chaves em Settings -> Integrations -> API.
- Armazenamento: o segredo é mostrado uma única vez. Mantenha-o no lado do servidor; rode as chaves expostas e revogue as não utilizadas.
Scopes
As chaves carregam scopes de privilégio mínimo. Um pedido sem o scope necessário devolve 403 com code: "SCOPE_REQUIRED".
| Scope | Concede |
|---|---|
items:read | Listar e ler itens |
items:write | Criar e atualizar itens |
orders:read | Listar encomendas |
contacts:read | Listar contactos |
organization:read | Ler o perfil da organização |
usage:read | Ler o resumo de utilização da API |
audit:read | Exportar eventos de auditoria (Enterprise) |
webhooks:read | Listar e ler endpoints de webhook |
webhooks:write | Criar e atualizar endpoints de webhook (Enterprise) |
webhooks:delete | Eliminar endpoints de webhook |
webhooks:deliveries:read | Ler tentativas de entrega de webhook |
Inspecionar uma credencial
GET /v1/auth/context devolve o tenant, o plano, os scopes, o nível de limite de taxa e a expiração da chave que faz a chamada: útil para diagnósticos e para falhar rapidamente quando falta um scope.
OAuth
OAuth é o modelo para aplicações parceiras. As aplicações aprovadas usam Authorization Code com PKCE para acesso mediado pelo utilizador, ou Client Credentials para acesso máquina-a-máquina confidencial aprovado.
Endpoints públicos:
GET /oauth/authorizePOST /oauth/tokenPOST /oauth/revoke
O endpoint de token emite uma chave de API de tenant com scope (uma credencial pk_live_* / pk_test_*) devolvida como access_token com token_type: Bearer. Envie-a como Authorization: Bearer <token> ou como X-API-Key. A API revalida o tenant, o plano, o estado da aplicação e os scopes em cada pedido, pelo que o acesso revogado ou rebaixado produz efeito imediato.
Autorização de MCP alojado
Os pedidos de MCP alojado usam credenciais bearer com scope para o recurso da API pública. As ferramentas MCP mapeiam um-para-um com os scopes da API pública, as ferramentas de escrita exigem um input de confirmação explícito e as credenciais não são persistidas pelo processo MCP.