Add token format spec

1 files changed, 30 insertions, 0 deletions

diff --git a/README.md b/README.md
index 9f00a1c..b7b527c 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,36 @@ Provides at least three core systems:
 - Rust 1.74+
 - git
 
+## Token Specification
+
+### Token Format
+
+Tokens are 128-bit (16 byte) UUIDs which are always base64 encoded using the URL-safe alphabet without padding.
+This means that every token is a 22-character string containing the alphabet: `[a-z][A-Z][0-9]_-`
+
+### Namespacing
+
+Tokens MUST always be generated within a namespace.
+If a namespace is not provided, the request is rejected.
+
+### Prefixing
+
+A prefix is an unsigned 14-bit value (Hex: 0x000-0x3FFF) as a means of uniquely identifying token sources.
+The 14-bit value has a maximum value of 16,384 (0-16383 inclusive).
+
+Prefixes MAY be set via a runtime configuration or defined in the datastore within a namespace. 
+Once defined in the datastore, such prefixes MUST NOT be changed.
+
+## API Specification
+
+Endpoints include:
+
+- `/ping` - liveness check
+- `/ready` - readiness check
+- `/api/` - API related documentation, including OpenAPI spec
+- `/health` - limited internal health data: backend DB type, latency to backend(s), cache usage, prefix (if enabled), signing pubkey (if enabled) 
+- `/` - Tokenize or Redeem endpoint, split per deployment.
+
 ## Notes
 
 - System should be self-contained / self-hosting.