Security & compliance

Authentication

Every endpoint outside the public catalogue requires a Bearer token. Tokens are scoped per integrator, carry a documented set of permissions, and are revocable at any time without affecting other clients. Both Authorization: Bearer <key> and X-Sente-Authorization: Bearer <key> are accepted on every authenticated endpoint — use the standard Authorization header for compatibility with the bulk of client libraries; the custom header is retained for cases where another middleware on the network path may strip or rewrite Authorization.

Bearer tokens

Default for server-to-server integrations. The token is opaque, ~40 characters, prefixed with sk_sandbox_ in sandbox or sk_live_ in production. Send it on every request:

GET /v1/citizens HTTP/1.1
Host: sente-rails.space
X-Sente-Authorization: Bearer sk_sandbox_xxxxxxxxxxxxxxxx

OAuth 2.0 client_credentials

For partner platforms (a city ERP, an enterprise integrator) the rail issues OAuth 2.0 client_credentials tokens with configurable scopes — for example citizens.read, assessments.write, oversight.read. The flow follows RFC 6749 §4.4 with no client-side deviations; any standard OAuth library works without modification.

mTLS for high-risk endpoints

Payment confirmation webhooks, oversight read endpoints under the OAG scope, and credential rotation are gated behind mutual TLS in addition to the Bearer token. The rail pins the client certificate against a registered per-integrator fingerprint set.

Request signing

Inbound webhooks from aggregators (MoMo, Airtel) and EFRIS-side callbacks are signed with HMAC-SHA256 over the raw request body using a shared secret. Verify before parsing:

import hmac, hashlib

def verify(secret: str, body: bytes, signature_header: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    # Constant-time compare against the value carried in X-Sente-Signature
    return hmac.compare_digest(expected, signature_header)

Data classification

Three tiers govern how the rail handles each data class. Higher tiers carry stricter logging, retention, and access controls.

• Tier 1 — Personal. National Identification Numbers, phone numbers, addresses, consent metadata. Never appears in URLs or log lines; only in indexed body fields with role-gated read. Soft- archive on erasure request preserves referential integrity for paid receipts under PFMA retention rules.
• Tier 2 — Financial. Payment Intent references, aggregator transaction IDs, FDN values, assessment totals. Audit- logged on every read and write. Aggregator-side balances are never persisted by the rail.
• Tier 3 — Operational. MDA catalogue, service catalogue, public statistics, integration status. Catalogue endpoints are public-read; statistics aggregate only.

Regulatory frameworks

Seven Ugandan regulatory frameworks fall within scope. Each is addressed by design — the architecture does the regulatory work, not a retrofitted policy layer.

Audit trail

Every state-changing operation is captured in an immutable audit log: actor, timestamp, target document, before / after payload. Oversight Mode C consumers read against this log scoped to their statutory remit.

{
  "doctype": "Assessment",
  "name": "ASSESS-2026-000123",
  "action": "submit",
  "actor": { "user": "clerk@gulu.gov.ug", "role": "Sente Rails Clerk" },
  "context": { "shift": "SHIFT-2026-000045", "mda": "GULU", "ip": "10.x.x.x" },
  "before": null,
  "after": { "status": "Assessed", "total_amount": 50000 },
  "occurred_at": "2026-05-25T08:30:11Z"
}

Production hardening

Two items remain queued for the pre-production pass before any live traffic moves through the rail:

• Intrusion detection. Edge-side request anomaly scoring with per-integrator baselines. Slated for the production hardening pass.
• Formal penetration test. Independent third-party test against the live URL, results published as an appendix to this documentation under the API explorer.