From f62e0b89523ac33d0f3b2d03b9520d5a368b05d4 Mon Sep 17 00:00:00 2001
From: Will Norris <will@tailscale.com>
Date: Tue, 2 Apr 2024 11:24:46 -0700
Subject: [PATCH] README: document permission model and grants

Updates #18
Updates #22
Updates #86
Updates #120

Signed-off-by: Will Norris <will@tailscale.com>
---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/README.md b/README.md
index 775b890..643cc8c 100644
--- a/README.md
+++ b/README.md
@@ -121,6 +121,49 @@ destination="/home/nonroot"
 
 </details>
 
+## Permissions
+
+By default, users own the golinks they create and only they can update or delete those links.
+Ownership can be transferred to another user from the link edit page.
+Links whose owner is no longer part of the tailnet can be edited by any user,
+at which point that user will become the new owner.
+
+Users can be granted admin access to edit all links using [ACL grants] in your tailnet policy file.
+For example, if you have your golink instance tagged with `tag:golink` and a user group named `group:golink-admins`,
+you can grant them admin access using:
+
+```json
+{
+  "grants": [{
+      "src": ["group:golink-admins"],
+      "dst": ["tag:golink"],
+      "app": {
+        "tailscale.com/cap/golink": [{
+            "admin": true
+        }]
+      }
+  }]
+}
+```
+
+Or if you want everyone to be able to edit all links, you could use `autogroup:member`:
+
+```json
+{
+  "grants": [{
+      "src": ["autogroup:member"],
+      "dst": ["tag:golink"],
+      "app": {
+        "tailscale.com/cap/golink": [{
+            "admin": true
+        }]
+      }
+  }]
+}
+```
+
+[ACL grants]: https://tailscale.com/kb/1324/acl-grants
+
 ## Backups
 
 Once you have golink running, you can backup all of your links in [JSON lines] format from <http://go/.export>.