diff --git a/README.md b/README.md
index db48469..26dfefa 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,60 @@ Mobile-first email template and report builder for Arrowstack applications.
 - MJML email rendering
 - HTML and A4 PDF report rendering
 - immutable publish versions
+- stable template keys for consuming apps
 - server-side Keycloak OIDC authorization-code + PKCE flow
+- authenticated published-template API
+- revocable hashed API keys
 - PostgreSQL persistence
 
+## Consumer API
+
+Drafts are editor-only. Consuming apps can only retrieve or render published versions.
+
+List published templates:
+
+```http
+GET /api/v1/templates
+X-API-Key: ts_live_...
+```
+
+Pull one published template:
+
+```http
+GET /api/v1/templates/{template-key}
+X-API-Key: ts_live_...
+```
+
+Render it with runtime data:
+
+```http
+POST /api/v1/templates/{template-key}/render
+X-API-Key: ts_live_...
+Content-Type: application/json
+
+{
+  "format": "pdf",
+  "data": {
+    "customer": {
+      "name": "Example Customer"
+    }
+  }
+}
+```
+
+Email templates accept `format: "email"` and return rendered HTML. Reports accept `html` or `pdf`.
+
+### Authentication
+
+Anonymous access is rejected.
+
+Two machine authentication modes are supported:
+
+1. `X-API-Key` using a key generated from the Template Studio **Use** screen. Keys are displayed once and stored only as SHA-256 hashes.
+2. `Authorization: Bearer <token>` using the Keycloak machine client `template-studio-api`.
+
+For another Arrowstack/Coolify application, prefer OAuth. The Arrowstack MCP secret broker can inject the existing `template-studio-api` client credentials directly into the consuming application without returning the client secret.
+
 ## Local development
 
 Copy `.env.example` to `.env`, provide a PostgreSQL database, and leave `AUTH_REQUIRED=false` for local-only development.