GraphQL Admin Usage

Este guia cobre o uso administrativo do GraphQL canonico da plataforma, exposto pelo Hasura.

Endpoint

• GraphQL endpoint: /v1/graphql (Hasura)

Use POST com Content-Type: application/json.

Autenticacao e autorizacao

• Envie Authorization: Bearer <jwt>.
• O usuario deve possuir role fsaap-admin no token.
• Se necessario, envie x-hasura-role: fsaap-admin para selecionar a role explicitamente.
• O token e mapeado para contexto Hasura (x-hasura-user-id, x-hasura-org-id e roles permitidas).

Introspection do schema

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

Use introspection para descobrir campos/tipos ativos no ambiente alvo.

Regras de seguranca (admin)

• Permissions de leitura sao definidas por tabela em hasura/src/metadata/databases/**/tables/*.yaml
• Para fsaap-admin, algumas tabelas removem filtro por organizacao, permitindo visao global
• Mutations nao sao usadas via Hasura neste dominio (escrita fica em REST)
• Se a role nao tiver select_permissions para um campo/tabela, a query falha por autorizacao

Exemplo de query administrativa

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

Importante: o schema final depende do metadata aplicado no Hasura do ambiente alvo; valide sempre via introspection.

Exemplo cURL

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

Quando usar REST

Operacoes de escrita/comando devem usar REST do backend (fsaap-agent-api e fsaap-rag).
No GraphQL (Hasura), o foco e consulta.

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/