Access Control

The Sankofa Engine enforces access control at three layers: application authentication, policy-based authorization, and infrastructure-level isolation. This page documents each layer.

Authentication

API Key Provisioning

API keys are provisioned by Sankofa Labs during customer onboarding. Customers do not self-register or self-provision credentials.

JWT Token Exchange

Clients authenticate by exchanging their API key credentials for a JWT bearer token:

Client                          API Gateway
  │                                  │
  │  POST /auth/token                │
  │  { client_id, client_secret }    │
  │ ────────────────────────────────▶│
  │                                  │  Validate credentials
  │                                  │  Generate JWT
  │  200 OK                          │
  │  { access_token, expires_in }    │
  │ ◀────────────────────────────────│
  │                                  │
  │  GET /api/v1/accounts            │
  │  Authorization: Bearer <JWT>     │
  │ ────────────────────────────────▶│
  │                                  │  Validate JWT signature
  │                                  │  Extract claims
  │                                  │  Enforce authorization
  │  200 OK                          │
  │ ◀────────────────────────────────│

Token Lifetime and Refresh

Short-lived tokens limit the window of exposure if a token is compromised.

ECDSA P-256 Transaction Signing (Self-Custody)

For customers who require self-custody of transaction authorization, the Sankofa Engine supports ECDSA P-256 digital signatures:

This model gives customers full control over transaction authorization without sharing private keys with Sankofa Labs.

Authorization

Casbin v2 RBAC Model

The Sankofa Engine uses Casbin v2 for role-based access control. Casbin evaluates every API request against a policy file that defines who can do what on which resources.

Policy Structure

Casbin policies follow a subject, object, action model:

p, role:admin,    /api/v1/accounts/*,   *
p, role:operator, /api/v1/accounts/*,   GET
p, role:operator, /api/v1/transactions, POST
p, role:auditor,  /api/v1/accounts/*,   GET
p, role:auditor,  /api/v1/audit/*,      GET

Built-in Roles and Permissions

Custom roles can be defined in the Casbin policy file to match customer-specific requirements.

Permission Enforcement

Authorization is enforced at the API Gateway middleware layer:

Incoming Request
       │
       ▼
┌─────────────────┐
│ JWT Validation   │  Verify token signature and expiration
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│ Claims Extraction│  Extract role, subject, and tenant from JWT
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│ Casbin Enforcer  │  Evaluate (subject, object, action) against policy
└───────┬─────────┘
        │
   ┌────┴────┐
   │         │
 Allow     Deny
   │         │
   ▼         ▼
 Route    403 Forbidden
 to        + audit log
 backend

Every authorization decision — both allow and deny — is logged for audit purposes.

Infrastructure Access Controls

Kubernetes Namespace Isolation

All Sankofa Engine components run in a dedicated sankofa-engine Kubernetes namespace:

Network Policies

Kubernetes NetworkPolicies restrict pod-to-pod communication to only the paths required by the architecture:

Default-deny policies ensure that any new pod added to the namespace has no network access until an explicit policy is created.

Secret Scoping

Secrets are scoped to individual services following the principle of least privilege:

Principle of Least Privilege

Every component in the Sankofa Engine operates with the minimum permissions required:

• Services authenticate to only the backends they need (e.g., shard workers access ScyllaDB but not PostgreSQL).
• KMS access is scoped per service — each service can only access the key paths it requires.
• Kubernetes RBAC grants only the verbs (get, list, watch) each service account needs.
• Network policies allow only the specific ingress and egress paths required by the architecture.