GraphQL Tenant Usage

Este guia documenta o uso do GraphQL canonico da plataforma, servido pelo Hasura.

Endpoint

• GraphQL endpoint: /v1/graphql (Hasura)

Use POST com Content-Type: application/json.

Autenticacao

• Envie Authorization: Bearer <jwt>.
• JWT validado pelo Hasura (Keycloak), com mapeamento para:
  • x-hasura-allowed-roles (a partir de realm_access.roles)
  • x-hasura-default-role
  • x-hasura-user-id (sub)
  • x-hasura-org-id (fsaap.orgId)
• Opcionalmente, envie x-hasura-role para selecionar uma role permitida no token (ex.: business-owner).

Introspection e schema

O schema de consulta deve vir da introspection do Hasura.

Exemplo para listar campos do query_root:

{
  "query": "query Introspection { __type(name: \"query_root\") { name fields { name } } }"
}

No projeto atual, introspection esta habilitada (disabled_for_roles: []).

Regras de autorizacao (tenant)

As queries seguem permissions do metadata do Hasura (row-level security):

• Escopo por organizacao via x-hasura-org-id
• Restricoes por role (business-admin, business-owner, business-attendant)
• Alguns datasets exigem tambem x-hasura-user-id (ex.: conversas do atendente)
• Mutations nao sao usadas neste fluxo; regras de insert/update/delete estao desabilitadas para o modelo de consulta

Exemplo de query

{
  "query": "query TenantUseCases($limit: Int = 20) { public_use_case(limit: $limit, where: {is_deleted: {_eq: false}}) { id name use_case_type updated_at } }",
  "variables": {
    "limit": 20
  }
}

Observacao: nomes finais de campos/tipos devem ser obtidos por introspection do ambiente alvo, pois o schema deriva do metadata aplicado no Hasura.

Exemplo cURL

curl -X POST "https:///v1/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer " \
  -H "x-hasura-role: business-owner" \
  -d '{
    "query": "query Introspection { __type(name: \"query_root\") { fields { name } } }"
  }'

Quando usar REST em vez de GraphQL

Para comandos/escrita, use os endpoints REST de fsaap-agent-api e fsaap-rag.
GraphQL (Hasura) e o canal oficial para queries.

Referencias

• OpenAPI do fsaap-agent-api: /contracts/fsaap-agent-api/latest.yaml
• OpenAPI do fsaap-rag: /contracts/fsaap-rag/latest.yaml
• Referencias centralizadas: /docs/api-references/