docs: Document access token creation and usage

docs/README.md

@@ -16,6 +16,7 @@ For a full list of all the fields available in for use in Argo, and a link to ex
 Some use-case specific documentation is available:
 
 * [Contributing](CONTRIBUTING.md)
+* [Access Token](access-token.md)
 * [Argo Workflow Architecture](architecture.md)
 * [Argo Server Auth Mode](argo-server-auth-mode.md)
 * [Argo Server SSO](argo-server-sso.md)

docs/access-token.md

@@ -0,0 +1,92 @@
+# Access Token
+
+If you want to automate tasks with the Argo Server API or CLI, you will need an access token. 
+
+Firstly, create a role with minimal permissions. This example role for jenkins only permission to update and list workflows:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: jenkins-role
+rules:
+  - apiGroups:
+      - ""
+    resources:
+      - workflows
+    verbs:
+      - list
+      - update
+```
+
+Create a service account for your service:
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: jenkins
+```
+
+Bind the service account to the role:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: jenkins
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: jenkins
+subjects:
+  - kind: ServiceAccount
+    name: jenkins
+```
+
+Create a secret:
+
+```yaml
+kind: Secret
+apiVersion: v1
+metadata:
+  name: jenkins
+  annotations:
+    kubernetes.io/service-account.name: jenkins
+type: kubernetes.io/service-account-token
+```
+
+This secret will be automatically populated with a token under ([learn more](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/)):
+
+```shell script
+ARGO_TOKEN=$(kubectl get secret jenkins -o yaml | grep -o 'token:.*' | sed 's/token: //')
+echo $ARGO_TOKEN
+ZXlKaGJHY2lPaUpTVXpJMU5pSXNJbXRwWkNJNkltS...
+```
+
+Use that token with the CLI (you need to set `ARGO_SERVER` too):
+
+```shell script
+ARGO_SERVER=http://localhost:2746 
+argo list
+```
+
+Use that token in your API requests, e.g. to list workflows:
+
+```shell script
+curl https://localhost:2746/api/v1/workflows/argo -H "Authorisation: Bearer $ARGO_TOKEN"
+# 200 OK
+```
+
+You should check you cannot do things you're not allowed!
+
+```shell script
+curl https://localhost:2746/api/v1/workflow-templates/argo -H "Authorisation: Bearer $ARGO_TOKEN"
+# 403 error
+```
+
+Token compromised?
+
+```shell script
+kubectl delete secret jenkins
+```

docs/rest-api.md

@@ -11,10 +11,12 @@ Since version v2.5 Argo Workflows ships with a server that provide more features
 The server can be configured with or without client auth (`server --auth-mode client`). When it is disabled, then clients must pass their Kubeconfig base 64 encoded in the HTTP `Authorization` header:
 
 ```
-token=$(argo auth token)
-curl -H "Authorization: $token" http://localhost:2746/api/v1/workflows/argo
+ARGO_TOKEN=$(argo auth token)
+curl -H "Authorization: $ARGO_TOKEN" http://localhost:2746/api/v1/workflows/argo
 ```
 
+Learn more on [how to generate an access token](access-token.md).
+
 To view the API:
 
 1. Open [https://editor.swagger.io/](https://editor.swagger.io/)