fix(docs/mint-api-key): correct sage scope set — identity:manage:*, not identity:create:*

POST /v1/identities requires relayauth:identity:manage:*. The scope
matcher treats 'manage' as implying create/read/write/delete, but
not the reverse — so an api-key with identity:create:* cannot call
that route. The previous example would succeed at mint and fail at
runtime with 403 insufficient_scope.

Caught while rotating sage's key during phase 122 wrap-up, 2026-04-23.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: kjgbot

docs/operations/api-key-minting.md

@@ -20,7 +20,7 @@ which is the wrong scope set entirely).
 ./scripts/mint-api-key.sh \
   --name sage-relayfile-minter \
   --scopes-json '[
-    "relayauth:identity:create:*",
+    "relayauth:identity:manage:*",
     "relayauth:token:create:*",
     "relayfile:fs:read:*",
     "relayfile:fs:write:*"
@@ -58,13 +58,23 @@ So sage's api-key needs:
 
 ```json
 [
-  "relayauth:identity:create:*",
+  "relayauth:identity:manage:*",
   "relayauth:token:create:*",
   "relayfile:fs:read:*",
   "relayfile:fs:write:*"
 ]
 ```
 
+Note: `POST /v1/identities` requires `relayauth:identity:manage:*`, not
+`create:*`. The scope matcher treats `manage` as implying
+`create/read/write/delete` (one-way). An api-key with only `create:*`
+gets 403 insufficient_scope on the route that demands `manage:*`. The
+same check-the-route pattern applies to every other scope string you're
+tempted to pick: grep `authenticateAndAuthorizeFromContext` /
+`authenticateBearerOrApiKeyAndAuthorize` in the route handler you
+intend to call, and match that exact scope string (or a broader
+superset).
+
 The relayfile scopes are required because the new identity sage creates
 inherits its own scopes from its sponsor's scope set (the api-key's
 synthesized claims). Without `relayfile:fs:*`, the minted token would

scripts/mint-api-key.sh

@@ -21,10 +21,17 @@
 # Usage:
 #   ./scripts/mint-api-key.sh \
 #     --name sage-relayfile-minter \
-#     --scopes-json '["relayauth:identity:create:*","relayauth:token:create:*","relayfile:fs:read:*","relayfile:fs:write:*"]' \
+#     --scopes-json '["relayauth:identity:manage:*","relayauth:token:create:*","relayfile:fs:read:*","relayfile:fs:write:*"]' \
 #     --to-gh-secret AgentWorkforce/cloud:SAGE_RELAYAUTH_API_KEY \
 #     --revoke-prior ak_3a7317be58de40f39ef18028393fd0f9
 #
+# Scope-picking note
+#   Scope actions are NOT commutative. The matcher treats `manage` as
+#   implying `create/read/write/delete`, but not the reverse — an
+#   api-key with `identity:create:*` cannot call a route that requires
+#   `identity:manage:*`. Always check the required-scope string at the
+#   route you need to call (see docs/operations/api-key-minting.md).
+#
 #   Common flags:
 #     --name <string>             Required. api-key name (operator-readable).
 #     --scopes-json <json-array>  Required. JSON array of scope strings.