Refine plugin documentation for clarity and completeness, including YAML configuration and token handling details.

Author: emanuel-quix

docs/quix-cloud/managed-services/plugin.md

@@ -2,9 +2,9 @@
 
 The plugin system enables services to expose an embedded UI inside Deployment Details (rendered as an iframe), and optionally add a shortcut in the environment’s left sidebar.
 
-Managed services could (or could not) populate these plugin properties automatically via the Managed Framework. You can always override them explicitly via YAML if needed.
+Managed services may populate these plugin properties automatically via the Managed Framework, and you can always override them explicitly in YAML.
 
-Non‑managed services can also define these properties in YAML, making any deployment of your pipeline behave like a plugin without being a managed service.
+Non‑managed services can also define these properties in YAML, making any deployment behave like a plugin without being a managed service.
 
 ## What it does
 
@@ -18,7 +18,7 @@ Non‑managed services can also define these properties in YAML, making any depl
 
 - Provide basic authentication integration with Quix Cloud so publicly exposed services don’t require a separate login
 
-## YAML
+## YAML configuration
 
 In your deployment YAML, you can enable the embedded UI and, optionally, a sidebar item:
 
@@ -39,15 +39,60 @@ Notes
 
 ## Embedded view URL
 
-When the plugin feature is enabled, the deployment exposes a public URL dedicated to the embedded UI. The Portal uses this URL to load the embedded view inside the iframe when `embeddedView` is enabled.
+When the plugin feature is enabled, the deployment exposes a public URL dedicated to the embedded UI. The Portal uses this URL to load the embedded view inside the iframe when `embeddedView` is enabled. This URL is not set in YAML; it’s exposed by the API.
 
 Population rules:
 
 - Managed service → Derived from Managed Services conventions.
-- Non‑managed service → The `publicAccess` configuration needs to be enabled.
+- Non‑managed service → Requires `publicAccess` to be enabled; resolves from the deployment’s public URL.
 
 ## Authentication and authorization
 
 The embedded view inherits authentication and authorization from the Quix platform: no separate login is required, and the same user/environment permissions apply.
 When an embedded view loads, the Plugin system injects the Quix user token into the iframe. The UI uses this token to call the backend securely.
 
+### How the token is injected in the embedded view
+
+On initial load of the embedded view (and on reload), the Portal provides the user token to the iframe so the UI can authenticate calls to the backend.
+
+### How to handle the token in the backend
+
+Install the Quix Portal helper package from the public feed:
+
+```bash
+pip install -i https://pkgs.dev.azure.com/quix-analytics/53f7fe95-59fe-4307-b479-2473b96de6d1/_packaging/public/pypi/simple/ quixportal
+```
+
+Then, in the backend service, validate the token and enforce authorization for each request. For example:
+
+```python
+
+import os
+
+from quixportal.auth import Auth
+
+# Instantiate authentication client. By default it will read
+# the portal API url from the environment variable Quix__Portal__Api
+auth = Auth()
+
+# Obtain the authorization token, traditionally passed as a header
+# Authorization: Bearer <token>
+token = ...
+
+# Example to obtain "Read" access to the "Workspace" resource
+resource_type = "Workspace"
+workspace_id = os.environ["Quix__Workspace__Id"]
+permissions = "Read"
+
+# Authorize the token bearer to access the resource
+if auth.validate_permissions(
+    token=token,
+    resourceType=resource_type,
+    resourceID=workspace_id,
+    permissions=permissions,
+):
+    print("Bearer is authorized to access the resource")
+else:
+    print("Bearer is not authorized to access the resource")
+
+```