From 6cb6de7e9c9a9a67d43cfb068a869103bc90c4ca Mon Sep 17 00:00:00 2001
From: David Hadley <davehadley@users.noreply.github.com>
Date: Thu, 27 Aug 2026 09:03:14 +0100
Subject: [PATCH] docs(authentication): document how to run authenticated
 workflows

---
 docs/how-tos/authentication.md | 43 ++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/how-tos/authentication.md b/docs/how-tos/authentication.md
index 9114addc8..63113e254 100644
--- a/docs/how-tos/authentication.md
+++ b/docs/how-tos/authentication.md
@@ -2,6 +2,49 @@
 
 Workflows uses [Keycloak](https://dev-guide.diamond.ac.uk/authn/how-tos/request-a-registration-with-keycloak/) for authentication.
 
+# User Instructions
+
+## How to call the Federated Graph from within a Workflow
+
+Diamond-II services are accessible via the [federated graph](https://dev-guide.diamond.ac.uk/the_graph/).
+All GraphQL queries, mutations, and subscriptions require [authentication through Keycloak](https://dev-guide.diamond.ac.uk/authn/).
+
+To enable authenticated access from a workflow, the following requirements must be met:
+
+- The workflow template must include the annotation `workflows.diamond.ac.uk/authenticated: "true"`.
+- The user submitting the Workflow must have logged in to <https://workflows.diamond.ac.uk>.
+
+When this annotation is present, the `GRAPH_URL` environment variable is automatically injected into the workflow. Applications running within the workflow can use this URL when making GraphQL queries and mutations.
+Authentication is handled automatically, there is no need to add `Authorization: Bearer ...` headers to your requests.
+Requests **must** be sent via `GRAPH_URL`. Direct requests to [graph.diamond.ac.uk](https://graph.diamond.ac.uk) still require Keycloak authentication.
+
+For example:
+
+```
+apiVersion: argoproj.io/v1alpha1
+kind: Workflow
+metadata:
+  generateName: example-authenticated-workflow
+spec:
+  entrypoint: get-workflow-templates
+
+  templates:
+    - name: get-workflow-templates
+      metadata:
+        annotations:
+          workflows.diamond.ac.uk/authenticated: "true"
+      container:
+        image: curlimages/curl:8.12.1
+        command: [sh, -c]
+        args:
+          - |
+            curl \
+              -X POST \
+              "${GRAPH_URL}" \
+              -H 'Content-Type: application/json' \
+              --data '{"query":"query WorkflowTemplates { workflowTemplates { nodes { name } } }"}'
+```
+
 # Developer Instructions
 
 ## How to Set up a Keycloak Client to work with Workflows via the Graph