website/docs: update flow context ref (cherry-pick #17723 to version-2025.10) (#17732)

website/docs: update flow context ref (#17723)

* website/docs: update flow context ref



* format



* Update website/docs/add-secure-apps/flows-stages/flow/context/index.mdx




* Update website/docs/add-secure-apps/flows-stages/flow/context/index.mdx




---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Signed-off-by: Jens L. <jens@beryju.org>
Co-authored-by: Jens L. <jens@goauthentik.io>
Co-authored-by: Dominic R <dominic@sdko.org>
Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>

Author: 4 people

authentik/stages/invitation/stage.py

@@ -11,10 +11,10 @@
 from authentik.stages.invitation.signals import invitation_used
 from authentik.stages.prompt.stage import PLAN_CONTEXT_PROMPT
 
-INVITATION_TOKEN_KEY_CONTEXT = "token"  # nosec
-INVITATION_TOKEN_KEY = "itoken"  # nosec
-INVITATION_IN_EFFECT = "invitation_in_effect"
-INVITATION = "invitation"
+QS_INVITATION_TOKEN_KEY = "itoken"  # nosec
+PLAN_CONTEXT_INVITATION_TOKEN = "token"  # nosec
+PLAN_CONTEXT_INVITATION_IN_EFFECT = "invitation_in_effect"
+PLAN_CONTEXT_INVITATION = "invitation"
 
 
 class InvitationStageView(StageView):
@@ -23,13 +23,13 @@ class InvitationStageView(StageView):
     def get_token(self) -> str | None:
         """Get token from saved get-arguments or prompt_data"""
         # Check for ?token= and ?itoken=
-        if INVITATION_TOKEN_KEY in self.request.session.get(SESSION_KEY_GET, {}):
-            return self.request.session[SESSION_KEY_GET][INVITATION_TOKEN_KEY]
-        if INVITATION_TOKEN_KEY_CONTEXT in self.request.session.get(SESSION_KEY_GET, {}):
-            return self.request.session[SESSION_KEY_GET][INVITATION_TOKEN_KEY_CONTEXT]
+        if QS_INVITATION_TOKEN_KEY in self.request.session.get(SESSION_KEY_GET, {}):
+            return self.request.session[SESSION_KEY_GET][QS_INVITATION_TOKEN_KEY]
+        if PLAN_CONTEXT_INVITATION_TOKEN in self.request.session.get(SESSION_KEY_GET, {}):
+            return self.request.session[SESSION_KEY_GET][PLAN_CONTEXT_INVITATION_TOKEN]
         # Check for {'token': ''} in the context
-        if INVITATION_TOKEN_KEY_CONTEXT in self.executor.plan.context.get(PLAN_CONTEXT_PROMPT, {}):
-            return self.executor.plan.context[PLAN_CONTEXT_PROMPT][INVITATION_TOKEN_KEY_CONTEXT]
+        if PLAN_CONTEXT_INVITATION_TOKEN in self.executor.plan.context.get(PLAN_CONTEXT_PROMPT, {}):
+            return self.executor.plan.context[PLAN_CONTEXT_PROMPT][PLAN_CONTEXT_INVITATION_TOKEN]
         return None
 
     def get_invite(self) -> Invitation | None:
@@ -60,8 +60,8 @@ def dispatch(self, request: HttpRequest) -> HttpResponse:
                 return self.executor.stage_ok()
             return self.executor.stage_invalid(_("Invalid invite/invite not found"))
 
-        self.executor.plan.context[INVITATION_IN_EFFECT] = True
-        self.executor.plan.context[INVITATION] = invite
+        self.executor.plan.context[PLAN_CONTEXT_INVITATION_IN_EFFECT] = True
+        self.executor.plan.context[PLAN_CONTEXT_INVITATION] = invite
 
         context = {}
         always_merger.merge(context, self.executor.plan.context.get(PLAN_CONTEXT_PROMPT, {}))

authentik/stages/invitation/tests.py

@@ -16,9 +16,9 @@
 from authentik.flows.views.executor import SESSION_KEY_PLAN
 from authentik.stages.invitation.models import Invitation, InvitationStage
 from authentik.stages.invitation.stage import (
-    INVITATION_TOKEN_KEY,
-    INVITATION_TOKEN_KEY_CONTEXT,
+    PLAN_CONTEXT_INVITATION_TOKEN,
     PLAN_CONTEXT_PROMPT,
+    QS_INVITATION_TOKEN_KEY,
 )
 from authentik.stages.password import BACKEND_INBUILT
 from authentik.stages.password.stage import PLAN_CONTEXT_AUTHENTICATION_BACKEND
@@ -89,7 +89,7 @@ def test_with_invitation_get(self):
 
         with patch("authentik.flows.views.executor.FlowExecutorView.cancel", MagicMock()):
             base_url = reverse("authentik_api:flow-executor", kwargs={"flow_slug": self.flow.slug})
-            args = urlencode({INVITATION_TOKEN_KEY: invite.pk.hex})
+            args = urlencode({QS_INVITATION_TOKEN_KEY: invite.pk.hex})
             response = self.client.get(base_url + f"?query={args}")
 
         session = self.client.session
@@ -114,7 +114,7 @@ def test_invalid_flow(self):
 
         with patch("authentik.flows.views.executor.FlowExecutorView.cancel", MagicMock()):
             base_url = reverse("authentik_api:flow-executor", kwargs={"flow_slug": self.flow.slug})
-            args = urlencode({INVITATION_TOKEN_KEY: invite.pk.hex})
+            args = urlencode({QS_INVITATION_TOKEN_KEY: invite.pk.hex})
             response = self.client.get(base_url + f"?query={args}")
 
         session = self.client.session
@@ -134,7 +134,7 @@ def test_with_invitation_prompt_data(self):
         )
 
         plan = FlowPlan(flow_pk=self.flow.pk.hex, bindings=[self.binding], markers=[StageMarker()])
-        plan.context[PLAN_CONTEXT_PROMPT] = {INVITATION_TOKEN_KEY_CONTEXT: invite.pk.hex}
+        plan.context[PLAN_CONTEXT_PROMPT] = {PLAN_CONTEXT_INVITATION_TOKEN: invite.pk.hex}
         session = self.client.session
         session[SESSION_KEY_PLAN] = plan
         session.save()

website/docs/add-secure-apps/flows-stages/flow/context/index.mdx

@@ -23,6 +23,8 @@ This section describes the data (the context) that are used in authentik, and pr
 Keys prefixed with `goauthentik.io` are used internally by authentik and are subject to change without notice, and should not be modified in policies in most cases.
 :::
 
+{/* To update this file, search for `PLAN_CONTEXT_\w+\s=` in the workspace to find all definitions. */}
+
 ### Common keys
 
 #### `pending_user` ([User object](../../../../users-sources/user/user_ref.mdx#object-properties))
@@ -201,6 +203,22 @@ Optionally override the email address that the email will be sent to. If not set
 
 If _Show matched user_ is disabled, this key will be set to the user identifier entered by the user in the identification stage.
 
+#### Invitation stage
+
+##### `invitation` (Invitation object)
+
+The invitation used with the invitation stage. When **Continue flow without invitation** is enabled, this may be unset.
+
+If the invitation was single-use, this object may hold a reference to an invitation that no longer exists in the database.
+
+##### `invitation_in_effect` (boolean)
+
+A boolean value that is `True` when an invitation has been used.
+
+##### `token` (string)
+
+This value can be set either via [Prompt data](#prompt_data-dictionary) or via policy to interactively/programmatically choose an invitation.
+
 #### Redirect stage
 
 ##### `redirect_stage_target` (string):ak-version[2024.12]