about summary refs log tree commit diff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md26
1 files changed, 25 insertions, 1 deletions
diff --git a/README.md b/README.md
index d6a2bdc..55374c0 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,10 @@ A Rust/Axum-based API server for GeneNetwork.
 | POST   | `/plot/bnw`                                       | The BNW network, as SVG.          |
 | GET    | `/compute/rqtl/status/{run_id}`                   | Poll an rqtl run's progress.      |
 | POST   | `/get-test-token`                                 | Get a test bearer token (local).  |
+| GET    | `/tokens`                                         | List short API tokens (local).    |
+| POST   | `/tokens`                                         | Mint a short API token (local).   |
+| DELETE | `/tokens/{id}`                                    | Revoke a short API token (local). |
+| GET    | `/tokens/who`                                     | Describe the presented credential (local). |
 | GET    | `/search`                                         | Search traits (free-text).        |
 | GET    | `/openapi.json`                                   | OpenAPI 3.1 document.             |
 
@@ -50,7 +54,27 @@ Every endpoint above requires a valid gn-auth bearer token
 (`Authorization: Bearer <token>`) except `/`, `/version`, `/openapi.json`
 and `/get-test-token` itself -- see docs/gn-auth.md and the
 "Development" section below (`POST /get-test-token`) for how to get
-one for local testing. A missing or invalid token is a 401; which
+one for local testing.
+
+**Short API tokens.** Beside gn-auth's JWT there is a second credential
+format for agents and scripts: `gn4ai_` + 64-char opaque tokens, stored as
+SHA-256 hashes in one SQLite database (`tokens.sqlite`, `GN4_API_TOKENS_DB`,
+chmod 0600, gitignored). Nothing is stored *in* the token, so revocation is
+deleting a row and takes effect on the next request; a token in a log line
+reveals nothing; and if the registry is lost every short token stops working.
+Mint, list, revoke and introspect with `scripts/gn4-token.py
+create|list|revoke|who`; the token is printed once and never again.
+Administration lives at `/tokens`, `/tokens/{id}` and `/tokens/who`, which
+**answer only a direct caller on this machine** (TCP peer address, plus a
+refusal for anything claiming to be proxied) -- minting credentials is not
+reachable from the network, and there is no switch to change that. A short
+token reads **public data only**: it works everywhere a token suffices, and on
+`#[gnauth(secured)]` endpoints for public rows; a confidential dataset answers
+403 telling the caller to use a JWT, since gn-auth cannot validate an opaque
+token. Send it as `Authorization: Bearer gn4ai_...` and never in a query
+string, which would land in nginx's log and in `next` links.
+
+A missing or invalid token is a 401; which
 further, resource-level authorization (if any) an endpoint checks once
 a token is valid is a separate, per-endpoint matter covered in each
 entry below.