Private platform administration

The operator console at https://admin.simamia.online uses these server-to-server endpoints. This API key is a private machine credential. Do not enter or embed it in browser JavaScript, public Swagger requests, mobile apps, or customer integrations. The Admin Next.js server checks its signed operator session and sends X-Simamia-Admin-Key over the private Compose network.

The console administers Simamia business data. The API does not provide Camel Accounts credential, Google connection, or identity lifecycle administration. Tenants are inferred from owner_sub fields on stored Simamia records; an identity with no business records does not appear here.

Authentication and setup

All paths are relative to /api/v1. The API requires:

X-Simamia-Admin-Key: <SIMAMIA_ADMIN_API_TOKEN>

The same random value is configured as the Go API’s SIMAMIA_ADMIN_TOKEN. Keep the matching value server side in the admin and api Compose services. At least 32 characters are required; if absent, admin routes return 503 ADMIN_DISABLED.

The Next.js admin service separately uses SIMAMIA_ADMIN_PASSWORD for operator login and SIMAMIA_ADMIN_SESSION_SECRET to sign an eight-hour HttpOnly, SameSite=Strict session cookie. See Admin setup and security for deployment configuration.

Endpoint map

resource must be one of businesses, customers, services, orders, team, or expenses. Admin lists default to 50 entries and cap pages at 200. q does a case-insensitive substring search across record JSON. The data API’s payments endpoint remains a read-only derived view; the admin API cannot edit it.

Create, update, and delete

Admin create and update payloads use the same flexible JSON resource shapes and validation as the ordinary business API. For example, customers need a non-empty name and phone; orders need customer, service, and a positive amount; expenses need description, category, date, and a positive amount. See each resource guide for its required properties and defaults.

The API assigns record IDs and tenant ownership on create. It ignores attempts to modify id, owner_sub, or ownerSub in an update. It shallow-merges a PATCH, validates the merged result, and preserves unspecified fields.

curl -X POST \
  -H "X-Simamia-Admin-Key: $SIMAMIA_ADMIN_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Asha Mushi","phone":"+255712345678"}' \
  "https://api.simamia.online/api/v1/admin/accounts/$OWNER_SUB/customers"

curl -X PATCH \
  -H "X-Simamia-Admin-Key: $SIMAMIA_ADMIN_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"phone":"+255713000000"}' \
  "https://api.simamia.online/api/v1/admin/accounts/$OWNER_SUB/customers/CUS-0001"

DELETE is permanent. There is no soft delete or restore. Every successful admin create, update, or delete appends an SQLite audit event with actor label, operation, resource, record ID, tenant subject, time, and changed property names. Property values are excluded. If an audit write fails after the record change succeeds, the API logs admin_audit_write_failed; monitor container logs for that event.

What the monitoring endpoints mean

• /admin/health pings the SQLite connection and reports API uptime plus whether the Camel Accounts and admin integrations are configured. It does not make an HTTP health call to Camel Accounts, inspect Docker state, or return service logs.
• /admin/usage estimates bytes from serialized JSON payloads only. SQLite indexes, WAL/journal files, backups, and logs are excluded.
• /admin/audit records changes made through protected admin CRUD. It is not a complete audit of all normal user API changes and does not capture sign-in attempts.

The full request/response contract is available in the OpenAPI 3.1 file and interactive Swagger reference. The admin proxy keeps its key private; do not use Swagger’s Try it out for admin operations against production.