API Reference

Admin — Users

Accounts that can sign in to the head-office dashboard, and the sessions behind that sign-in. Every route needs X-Admin-Key — the dashboard server calls these on the browser's behalf, so browsers never hold the admin key.

POSTSign inExchanges email + password for a session token valid for 12 hours.
GETRead sessionValidates a token and returns the user behind it.
POSTSign outDeletes the session (HTTP DELETE).
GETList usersAll dashboard accounts. Password hashes are never returned.
POSTAdd a userCreates a dashboard account with a role.
POSTDeactivate userBlocks sign-in and invalidates existing sessions.
POSTActivate userRe-enables a deactivated account.

Sign in

Exchanges email + password for a session token valid for 12 hours.

POST/api/v1/admin/auth/login

Auth: X-Admin-Key

Body — required

Field	Type	Description
email	string	The user's email address.
password	string	The user's password.

Request

curl -X POST https://13-247-53-102.sslip.io/api/v1/admin/auth/login \
  -H 'X-Admin-Key: your_admin_key' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "admin@prevailgroup.co.zw", "password": "..." }'

Response

Field	Type	Description
token	string	Opaque session token. The dashboard stores it in an httpOnly cookie.
expiresAt	string	ISO-8601 expiry, 12 hours from sign-in.
user	object	The signed-in user: id, email, name, role, active, createdAt.

Returns 401 for a wrong password, an unknown email, or a deactivated account.

Read session

Validates a token and returns the user behind it.

GET/api/v1/admin/auth/session/{token}

Auth: X-Admin-Key

Path parameters

Field	Type	Description
token	string	Session token from login.

Request

curl https://13-247-53-102.sslip.io/api/v1/admin/auth/session/<token> \
  -H 'X-Admin-Key: your_admin_key'

Expired sessions and deactivated users return 404 and the session is deleted.

Sign out

Deletes the session (HTTP DELETE).

POST/api/v1/admin/auth/session/{token}

Auth: X-Admin-Key

Path parameters

Field	Type	Description
token	string	Session token to revoke.

Request

curl -X DELETE https://13-247-53-102.sslip.io/api/v1/admin/auth/session/<token> \
  -H 'X-Admin-Key: your_admin_key'

List users

All dashboard accounts. Password hashes are never returned.

GET/api/v1/admin/users

Auth: X-Admin-Key

No parameters.

Request

curl https://13-247-53-102.sslip.io/api/v1/admin/users -H 'X-Admin-Key: your_admin_key'

Response · 200

[
  { "id": 1, "email": "admin@prevailgroup.co.zw", "name": "Head Office", "role": "SUPER_ADMIN", "active": true },
  { "id": 2, "email": "viewer@prevailgroup.co.zw", "name": "Report Viewer", "role": "VIEWER", "active": true }
]

Add a user

Creates a dashboard account with a role.

POST/api/v1/admin/users

Auth: X-Admin-Key

Body — required

Field	Type	Description
email	string	Unique email address; used to sign in.
name	string	Display name.
password	string	At least 8 characters. Stored bcrypt-hashed.
role	enum	SUPER_ADMIN (manage SBUs, keys and users) or VIEWER (read-only).

Request

curl -X POST https://13-247-53-102.sslip.io/api/v1/admin/users \
  -H 'X-Admin-Key: your_admin_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "tendai@prevailgroup.co.zw",
    "name": "Tendai Moyo",
    "password": "a-strong-password",
    "role": "VIEWER"
  }'

Deactivate user

Blocks sign-in and invalidates existing sessions.

POST/api/v1/admin/users/{id}/deactivate

Auth: X-Admin-Key

Path parameters

Field	Type	Description
id	integer	The user's id.

Request

curl -X POST https://13-247-53-102.sslip.io/api/v1/admin/users/2/deactivate \
  -H 'X-Admin-Key: your_admin_key'

Activate user

Re-enables a deactivated account.

POST/api/v1/admin/users/{id}/activate

Auth: X-Admin-Key

Path parameters

Field	Type	Description
id	integer	The user's id.

Request

curl -X POST https://13-247-53-102.sslip.io/api/v1/admin/users/2/activate \
  -H 'X-Admin-Key: your_admin_key'