SREDSimplify Docs

Appearance

Runbook: Admin Access And Invitation Failures ​

Trigger: Admin users cannot reach /api/v1/admin/**, invitation operations fail, or admin mutations are unexpectedly rejected. Impact: Operators may be blocked from managing users, invitations, quotas, billing config, or expert review workflows.

Quick triage ​

  1. Identify the actual response class: 401, 403, 400, 429, or 5xx.
  2. Confirm the caller is using a fresh bearer token.
  3. Confirm the current user still has the ADMIN role.
  4. Check whether the failure is broad across all admin routes or isolated to one endpoint group.

If the failures are mostly 401 ​

Check:

  • frontend refresh flow health
  • current access token validity
  • whether the BFF is forwarding Authorization correctly
  • whether the admin user can still call GET /api/v1/auth/me

Relevant docs:

If the failures are mostly 403 ​

Check:

  • whether the account was downgraded from ADMIN
  • whether the user is in the wrong environment or logged into the wrong account
  • whether the route is truly /api/v1/admin/** and not another protected surface

If the failures are mostly 400 ​

Common admin-specific business-rule rejections:

  • attempting to suspend the last remaining admin
  • attempting to demote the last remaining admin
  • malformed or missing required mutation input

For invitation operations, also check:

  • whether createdBy was supplied as a query parameter
  • whether the requested invitation code actually exists before revoke/read

If the failures are mostly 429 ​

Check:

  • whether the admin is repeatedly retrying a write route such as invitation generation, user mutation, billing config update, or quota update
  • whether a local script or admin UI loop is unintentionally hammering the endpoint

If the failures are 5xx ​

Check:

  • backend actuator health
  • recent auth or role-mapping changes
  • billing/quota service logs if the failure is isolated to those config surfaces
  • storage or project-file access if the failure is isolated to expert review ZIP download

Endpoint-group notes ​

Invitations ​

Routes under /api/v1/admin/invitations return raw strings and entities. Callers expecting ApiResponse<T> may mis-handle success and error bodies.

Users ​

Routes under /api/v1/admin/users return raw DTOs and can reject last-admin suspend/demote operations with 400.

Billing and quotas ​

Routes under /api/v1/admin/billing and /api/v1/admin/quotas use ApiResponse<T> and are better candidates for generic admin clients.

Escalation ​

If operators cannot perform admin actions for more than 5 minutes:

  1. Page the backend owner
  2. Capture the failing admin route, response code, and affected user ID
  3. Record whether the issue is auth, role drift, throttling, or business-rule rejection

Post-action ​

  1. Link the failing surface to Admin APIs.
  2. Update this runbook if the failure mode was not already described.