From 8bf68b2b7642449f352e57a0ac79b8a30047dad8 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Thu, 22 Oct 2026 10:54:25 +0000 Subject: [PATCH] docs: describe what OAuth scopes and tags limit --- docs/ref/api.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/ref/api.md b/docs/ref/api.md index 858aa1d1b..0c4741baf 100644 --- a/docs/ref/api.md +++ b/docs/ref/api.md @@ -78,6 +78,17 @@ secret is shown once: headscale oauth-clients create --scope auth_keys --tag tag:ci ``` +Scopes apply to the whole tailnet, as in Tailscale: an `auth_keys` token can read +and revoke auth keys of any tag, an `oauth_keys` token every OAuth client, and a +`devices:core:read` token reads every device, routes included with `fields=all`. +Keep the secret as safe as any credential that can revoke keys. Without +`all=true`, a token lists only the auth keys made through a token, whatever their +tags; with it, every valid auth key. No listing holds a spent, expired or revoked +key. Tags limit only the tags a token puts on keys, clients and devices, and +which tagged devices it may retag. Deleting an OAuth client revokes its secret +and its access tokens; auth keys, clients and nodes created with it stay until +you remove them. + Build the auth key from the secret: 1. Swap the prefix: `hskey-client-…` becomes `tskey-client-…`. The client only