Context
- The nginx
issuer.block closes the/{slug}/admin/path withallow 127.0.0.1; deny all; the application expectsx-admin-token(a single token shared by all tenants). This is right for the demo portal (same server). - With D10/D14 a client was written for external institutions (issuerThe institution that signs and issues credentials: a university, a professional body, a public institution or a company.s) (
@tamga-network/issuer/client:createOffer,sellTicket,revoke…); in production there is no safe way to reach these endpoints from outside. Giving the shared admin key to institutions would let one tenant revoke another tenant's credentials.
Decision
- K1 — Separate surface:
/{slug}/api/v1/*(offers, tickets, revocations)./{slug}/admin/*stays internal (127.0.0.1). - K2 — Tenant API key: one or more keys per institution;
Authorization: Bearer tmg_<slug>_<random>. The server stores only the digest (SHA-256); the key is shown once, at creation. A key is bound to aslugand a scope (offers:write,tickets:write,revocations:write); it is invalid on another tenant's path. - K3 — Rotation and revocation: keys have an expiry date (suggested 90 days); two keys may be valid at the same time (seamless rotation); revocation takes effect immediately.
- K4 — Limits: a rate limit per key and a request size limit; the audit record holds the key identifier (digest prefix) and the event name — no personal data and never the key itself (PR14/AP3).
- K5 — Pilot option: for institutional integrations such as a university, mTLS (the institution's X.509 certificate, matching its entry in the trust listA signed list of a country's root certificates, issuers and registered relying parties. Today trust in Tamga rests on these lists; a shared ledger comes later.) can be made mandatory in addition to K2.
- K6 — Client:
createIssuerClient({ baseUrl, slug, apiKey });adminTokenremains for internal use only.
Rationale / alternatives
- Exposing the shared admin key: no authorisation between tenants → rejected.
- OAuth 2.0 client credentials: correct, but needs an extra authorisation server; heavy for the first institutions. K2 can move to OAuth later.
- mTLS only: strong, but certificate management is a barrier for small sellers; K5 is kept as an option.
Invariants
| # | Rule |
|---|---|
| HA1 | External access only with a tenant-bound, scoped API key; the shared admin key is never exposed. |
| HA2 | The server stores an API key only as its digest; logs and audit records never contain the key itself. |
| HA3 | A key is valid only on its own slug's paths and for operations within its scope. |
Status
Accepted — 2026-09-27. DECISIONS: D-API-1. Note: K5 (mTLS) will be assessed in the pilot university integration.
Implementation: API routes and key store in apps/issuer (operator repository), the nginx api/v1 block, the apiKey option in issuer/client, the institution guide (docs site).