proofpoint-quarantine-portal/docs/api.md

HTTP API reference

All /api/* routes require an authenticated session. State-changing methods (non-GET) require an X-CSRF-Token header whose value comes from GET /api/config → csrf_token. Unauthorised API calls return 401; non-admin calls to admin routes return 403.

Auth (auth.py)

Method	Path	Purpose
GET/POST	/login	OIDC: redirect to Okta. Static: render/submit the dev form.
GET	/authorize	OIDC callback; validates token, checks allowed-users, sets session.
GET	/logout	Clear session.

Quarantine (app.py)

Method	Path	Returns
GET	/	The single-page UI.
GET	/api/config	{folders, deleted_folder, report_release, prefs, csrf_token, config_version, is_admin}
GET	/api/messages?folder=&limit=&before=	{folder, messages[], page:{raw_count, oldest, has_more}}
GET	/api/message/<guid>	{headers, text, html, attachments[], raw_headers}
POST	/api/actions	202 {job_id, queued} — body {action, folder, messages[], targetfolder?}
GET	/api/jobs	{jobs[], config_version} — scoped to the caller (admins see all)
GET/PUT/DELETE	/api/prefs	Per-user preferences (get / set patch / reset)

action ∈ release | report_release | delete | move. messages[] items carry {localguid, guid, subject, sender, recipient}. For move, targetfolder must be a configured folder.

Paging /api/messages

The PPS API caps a search at 1000 rows and has no offset paging. The client pages the whole folder backwards by date: fetch a page, then pass the oldest date seen as before for the next page, until page.has_more is false. page.oldest is the oldest date in the raw batch (before hidden/acted messages are filtered), so paging never terminates early.

Admin (admin.py, all @admin_required)

Method	Path	Returns
GET	/admin	The admin panel page.
GET	/api/admin/config	{config: redacted, schema, version} — secrets shown as *_set booleans
PUT	/api/admin/config	{version, applied[], restart_required[], config} / 400 {errors:[{field,message}]}
POST	/api/admin/pps-test	{ok, detail} — probes PPS with pending form values, never persists
GET	/api/admin/jobs?limit=	{jobs[], active} — all users
POST	/api/admin/jobs/<id>/retry	{job_id, status} — failed → pending
GET	/api/admin/logs?source=ops\|app&lines=&q=	{source, lines:[{text, level}], truncated}

Users and the denied message are ordinary config keys under [auth], saved through PUT /api/admin/config (one atomic write). source is an enum, never a file path.

Error shape

PPS failures return 502 {error, detail, status, reqid} (reqid = the PPS x-pps-reqid header, for cross-referencing PPS logs). Validation failures return 400 {errors:[…]} or 400 {error}.