about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/www/SKILL.md28
1 files changed, 28 insertions, 0 deletions
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md
index b6864c1..b4454ec 100644
--- a/docs/www/SKILL.md
+++ b/docs/www/SKILL.md
@@ -152,6 +152,34 @@ curl -s -H "$AUTH" --get --data-urlencode locus=<peak marker> --data window=1000
 Give the user the SVGs (they render directly) and quote the `x-plot-summary`
 header (peak, and the reference lines drawn when you asked for them).
 
+### Short API tokens (`gn4ai_...`)
+
+A second credential format beside gn-auth's JWT, for agents and scripts that
+should not carry a user's password or a long-lived JWT. Opaque: nothing is
+stored inside it, and everything about it lives in the server's registry (one
+SQLite database, `tokens.sqlite`).
+
+- **Administer them from this machine only.** `scripts/gn4-token.py
+  create|list|revoke|who` (routes `/tokens`, `/tokens/{id}`, `/tokens/who`).
+  Those routes answer only a direct caller on this machine — the server checks
+  the TCP peer address, not a header — and a request that arrives through a
+  proxy is refused, so this can never be driven from the network.
+- **The token is shown exactly once**, by `create`. Only its SHA-256 is stored;
+  there is no way to recover or enumerate one. `list` shows id, subject, scope,
+  status, prefix, expiry and last use.
+- **Send it as `Authorization: Bearer gn4ai_...`** — never as a query
+  parameter, which would land in nginx's log and in `next` links.
+- **Public data only.** It works on every token-only endpoint (search, compute,
+  plots, genotype metadata and frequencies, baskets, uploads, matrices) and on
+  secured endpoints for public rows; a confidential dataset answers 403 telling
+  the caller to use a gn-auth JWT, because gn-auth cannot validate an opaque
+  token.
+- **Revocation takes effect on the next request**, with no restart: it is a row
+  in the registry. Expiry is fixed when minted (30 days by default).
+- 64 characters, `gn4ai_` + 56 body characters + a 2-character checksum, from an
+  alphabet with no look-alikes (`0/O`, `1/l/I`) — a typo is refused before the
+  registry is asked.
+
 ### Which GEMMA endpoint: ravanan by default
 
 Two endpoints run the same computation, and the reply shape is identical: