suap-api

SUAP API (v2) access

SUAP is the unified admin system used by many Brazilian federal institutes. IFRN developed it; other institutes (IFF, IFS, ...) run their own instances, each with its own base URL (e.g. https://suap.iff.edu.br, https://suap.ifrn.edu.br). The API is django-ninja (Swagger UI at /api/docs/). The API surface and auth behaviour differ slightly per instance — always verify against that instance's live /api/openapi.json.

Auth flow (the critical part)

Token endpoint: POST {base}/api/v2/autenticacao/token/.

Gotcha 1 — WAF blocks a missing User-Agent. Without a User-Agent header the nginx/WAF returns 403 Forbidden immediately (looks like a hard block, but it's just the UA). Always send User-Agent: Mozilla/5.0.

Gotcha 2 — body is username/password, NOT Basic Auth. The IFRN suapi example and some docs suggest Basic Auth, but the IFF instance returns 422 ("missing user_token") for Basic Auth and 400 ("username is required", "password is required") when those keys are absent. Working request:

curl -s -X POST "{base}/api/v2/autenticacao/token/" \
  -H "User-Agent: Mozilla/5.0" \
  -H "Content-Type: application/json" \
  -d '{"username": "<matricula>", "password": "<senha>"}'

Response (HTTP 200): {"username": "...", "refresh": "<JWT>", "access": "<JWT>"}. Use the access JWT as the Bearer token: Authorization: Bearer <access>.

Discovering the real endpoints

Old docs/examples use paths like /api/v2/edu/alunos/{mat}/ — these return 404 on the IFF instance. The actual student endpoints live under /api/ensino/.... To get the authoritative, current path list for an instance, fetch its OpenAPI spec (the spec URL hides inside the /api/docs/ HTML as /api/openapi.json):

curl -s "{base}/api/openapi.json" -o openapi.json

Then inspect paths for keywords (boletim, periodo, aluno, historico, nota, disciplina) and read components.securitySchemes (it's JWTAuth/bearer). Loop over each candidate path with the Bearer token to see what actually returns data.