docs: remove reliance on subscription header in inference and models endpoint (#614)

<!--- Provide a general summary of your changes in the Title above -->

## Description
<!--- Describe your changes in detail -->

## How Has This Been Tested?
<!--- Please describe in detail how you tested your changes. -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->

## Merge criteria:
<!--- This PR will be merged by any repository approver when it meets
all the points in the checklist -->
<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [ ] The commits are squashed in a cohesive manner and have meaningful
messages.
- [ ] Testing instructions have been added in the PR body (for PRs
involving changes that are not immediately obvious).
- [ ] The developer has manually tested the changes and verified that
the changes work


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Clarified API key authentication flow: keys now bind to a specific
subscription at creation time
* Updated guidance on when to use `X-MaaS-Subscription` header—required
only for user tokens with multiple subscriptions, not for API key-based
inference
* Revised model listing and inference examples to reflect the new
subscription binding behavior for API keys
* Updated authentication flow diagrams and troubleshooting guidance to
reflect current behavior

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Jim Rhyness <jrhyness@redhat.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: 3 people

docs/content/architecture.md

@@ -214,7 +214,7 @@ The MaaSAuthPolicy delegates to the MaaS API for key validation and subscription
 2. MaaS API validates the key (format, not revoked, not expired) and returns username, groups, and subscription.
 3. Authorino calls MaaS API to check subscription (groups, username, requested subscription from the key).
 4. If the user lacks access to the requested subscription → error (403).
-5. On success, returns selected subscription; Authorino caches the result (e.g., 60s TTL). AuthPolicy may inject `X-MaaS-Subscription` for downstream rate limiting.
+5. On success, returns selected subscription; Authorino caches the result (e.g., 60s TTL). AuthPolicy may inject `X-MaaS-Subscription` **server-side** for downstream rate limiting and metrics. Clients do not send this header on inference; subscription comes from the API key record created at mint time.
 
 ```mermaid
 graph TB

docs/content/configuration-and-management/maas-controller-overview.md

@@ -220,14 +220,11 @@ flowchart LR
 
 ## 9. Authentication (Current Behavior)
 
-For **GET /v1/models**, the API forwards the client’s **Authorization** header as-is to each model endpoint (no token exchange). For inference, until MaaS API token minting is in place, use the **OpenShift token**:
+For **GET /v1/models**, the maas-api forwards the client’s **Authorization** header as-is to each model endpoint (no token exchange). You can use an **OpenShift token** or an **API key** (`sk-oai-*`). With a user token, you may send `X-MaaS-Subscription` to filter when you have access to multiple subscriptions.
 
-```bash
-export TOKEN=$(oc whoami -t)
-curl -H "Authorization: Bearer $TOKEN" "https://<gateway-host>/llm/<model-name>/v1/chat/completions" -d '...'
-```
+For **model inference** (requests to `…/llm/<model>/v1/chat/completions` and similar), use an **API key** created via `POST /v1/api-keys` only. Each key is bound to one MaaSSubscription at mint time.
 
-The Kuadrant AuthPolicy validates this token via **Kubernetes TokenReview** and derives user/groups for authorization and for the identity passed to TokenRateLimitPolicy (including `groups_str`).
+The Kuadrant AuthPolicy validates API keys via the MaaS API and validates user tokens via `Kubernetes TokenReview`, deriving user/groups for authorization and for TokenRateLimitPolicy (including `groups_str`).
 
 ---
 

docs/content/configuration-and-management/model-listing-flow.md

@@ -64,8 +64,6 @@ The `/v1/models` endpoint automatically filters models based on your authenticat
 #### API Key Authentication (Bearer sk-oai-*)
 When using an API key, the subscription is automatically determined from the key:
 - Returns **only** models from the subscription bound to the API key at mint time
-- The `X-MaaS-Subscription` header is automatically injected by the gateway
-- **No manual headers required**
 
 ```bash
 # API key bound to "premium-subscription"

docs/content/configuration-and-management/quota-and-access-configuration.md

@@ -222,12 +222,6 @@ When a user belongs to multiple groups that each have a subscription, the access
 
 ## Troubleshooting
 
-### 403 Forbidden: "must specify X-MaaS-Subscription"
-
-**Cause:** User has multiple subscriptions and did not send the header.
-
-**Fix:** Add `X-MaaS-Subscription: <subscription-name>` to the request.
-
 ### 403 Forbidden: "no access to subscription"
 
 **Cause:** User requested a subscription they do not belong to (group membership).

docs/content/configuration-and-management/subscription-overview.md

@@ -6,7 +6,7 @@ MaaSAuthPolicy and MaaSSubscription are namespace-scoped to `models-as-a-service
 
 ```mermaid
 flowchart TD
-    User([User / App]) -- "Request (Model + SubID)" --> Gateway{MaaS API Gateway}
+    User([User / App]) -- "Request (API key + model)" --> Gateway{MaaS API Gateway}
 
     subgraph Validation ["Dual-Check Gate"]
         direction LR

docs/content/configuration-and-management/token-management.md

@@ -107,7 +107,7 @@ sequenceDiagram
     DB-->>MaaS: username, groups, subscription, status
     MaaS->>MaaS: Check status (active/revoked/expired)
     MaaS-->>AuthPolicy: 4. valid: true, userId, groups, subscription
-    AuthPolicy->>AuthPolicy: Subscription check, inject headers (incl. X-MaaS-Subscription), rate limits
+    AuthPolicy->>AuthPolicy: Subscription check, inject headers, rate limits
     AuthPolicy->>Model: 5. Authorized request (identity headers)
     Model-->>Gateway: Response
     Gateway-->>User: Response
@@ -138,9 +138,12 @@ flowchart LR
 
 This means you can:
 
-1. **Authenticate with OpenShift or OIDC** — use your existing identity and the same token you would use for inference.
-2. **Use an API key** — use your `sk-oai-*` key in the Authorization header.
-3. **Call `/v1/models` immediately** — see only the models you can access, without creating an API key first (if using OpenShift token).
+1. **Authenticate with OpenShift or OIDC** — use your existing identity token for `GET /v1/models` (optional `X-MaaS-Subscription` when you have multiple subscriptions).
+2. **Use an API key** — use your `sk-oai-*` key in the Authorization header for listing and for inference.
+3. **Call `/v1/models` immediately** — see only the models you can access, without creating an API key first (if using an OpenShift token).
+
+!!! note "Inference vs listing"
+    Inference (calls to each model’s chat/completions URL) requires an API key in `Authorization: Bearer` only. Do not send `X-MaaS-Subscription` on inference—the subscription is the one bound at API key mint time. `GET /v1/models` accepts either an API key or an OpenShift token; with a user token, `X-MaaS-Subscription` remains supported for filtering.
 
 ---
 

docs/content/install/validation.md

@@ -33,7 +33,7 @@ API_KEY_RESPONSE=$(curl -sSk \
   -H "Authorization: Bearer $(oc whoami -t)" \
   -H "Content-Type: application/json" \
   -X POST \
-  -d '{"name": "validation-key", "description": "Key for validation", "expiresIn": "1h"}' \
+  -d '{"name": "validation-key", "description": "Key for validation", "expiresIn": "1h", "subscription": "simulator-subscription"}' \
   "${HOST}/maas-api/v1/api-keys") && \
 API_KEY=$(echo $API_KEY_RESPONSE | jq -r .key) && \
 echo "API key obtained: ${API_KEY:0:20}..."
@@ -43,21 +43,16 @@ echo "API key obtained: ${API_KEY:0:20}..."
     The plaintext API key is returned **only at creation time**. We do not store the API key, so there is no way to retrieve it again. Store it securely when it is displayed. If you run into errors, see [Troubleshooting](troubleshooting.md).
 
 !!! note
-    For more information about API keys, see [Understanding Token Management](../configuration-and-management/token-management.md).
+    `subscription` is the MaaSSubscription metadata name to bind (here `simulator-subscription` matches the [maas-system](https://github.com/opendatahub-io/models-as-a-service/tree/main/docs/samples/maas-system) free sample). Use your own name or omit the field to auto-select by `spec.priority`. For details, see [Understanding Token Management](../configuration-and-management/token-management.md).
 
 ### 3. List Available Models
 
-Set the subscription name (required when your API key matches multiple subscriptions; use the name from your MaaSSubscription CR):
-
-```bash
-export MaaS_SUBSCRIPTION="simulator-subscription"  # or your subscription name
-```
+Each API key is bound to one MaaSSubscription at creation time. `GET /v1/models` with an API key does not require `X-MaaS-Subscription`—the list is scoped to that subscription. (With an OpenShift user token instead of an API key, you can optionally send `X-MaaS-Subscription` to filter when you have access to multiple subscriptions.)
 
 ```bash
 MODELS=$(curl -sSk ${HOST}/maas-api/v1/models \
     -H "Content-Type: application/json" \
-    -H "Authorization: Bearer $API_KEY" \
-    -H "X-MaaS-Subscription: ${MaaS_SUBSCRIPTION}" | jq -r .) && \
+    -H "Authorization: Bearer $API_KEY" | jq -r .) && \
 echo $MODELS | jq . && \
 MODEL_NAME=$(echo $MODELS | jq -r '.data[0].id') && \
 MODEL_URL=$(echo $MODELS | jq -r '.data[0].url') && \

docs/content/user-guide/self-service-model-access.md

@@ -38,7 +38,7 @@ API_KEY_RESPONSE=$(curl -sSk \
   -H "Authorization: Bearer ${OC_TOKEN}" \
   -H "Content-Type: application/json" \
   -X POST \
-  -d '{"name": "my-api-key", "description": "Key for model access", "expiresIn": "90d"}' \
+  -d '{"name": "my-api-key", "description": "Key for model access", "expiresIn": "90d", "subscription": "simulator-subscription"}' \
   "${MAAS_API_URL}/maas-api/v1/api-keys")
 
 API_KEY=$(echo $API_KEY_RESPONSE | jq -r .key)
@@ -48,7 +48,7 @@ echo "Key prefix: ${API_KEY:0:16}..."
 echo "Bound subscription: ${SUBSCRIPTION}"
 ```
 
-To pin a specific subscription, add it to the JSON body, for example: `"subscription": "my-team-subscription"`.
+Replace `simulator-subscription` with your MaaSSubscription metadata name, or remove the `subscription` field to bind the **highest-priority** subscription you can access.
 
 !!! warning "API key shown only once"
     The plaintext API key is returned **only at creation time**. We do not store the API key, so there is no way to retrieve it again. Store it securely when it is displayed. If you run into errors, see [Troubleshooting](../install/troubleshooting.md).
@@ -110,6 +110,8 @@ echo $MODEL_INFO | jq .
 
 ## Making Inference Requests
 
+Use **only** your API key in `Authorization: Bearer`. The subscription is fixed when the key was created.
+
 ### Basic Chat Completion
 
 Make a simple chat completion request:

maas-api/README.md

@@ -193,7 +193,8 @@ API_KEY_RESPONSE=$(curl -sSk \
   -X POST \
   -d '{
     "name": "my-api-key",
-    "description": "Production API key for my application"
+    "description": "Production API key for my application",
+    "subscription": "simulator-subscription"
   }' \
   "${HOST}/maas-api/v1/api-keys")
 
@@ -208,14 +209,18 @@ API_KEY_RESPONSE=$(curl -sSk \
   -d '{
     "name": "my-short-lived-key",
     "description": "30-day test key",
-    "expiresIn": "30d"
+    "expiresIn": "30d",
+    "subscription": "simulator-subscription"
   }' \
   "${HOST}/maas-api/v1/api-keys")
 
 echo $API_KEY_RESPONSE | jq -r .
 API_KEY=$(echo $API_KEY_RESPONSE | jq -r .key)
 ```
 
+> [!NOTE]
+> Replace `simulator-subscription` with your `MaaSSubscription` metadata name. To rely on **auto-selection** instead, remove the `subscription` field; maas-api then picks the accessible subscription with the highest `spec.priority`.
+
 > [!IMPORTANT]
 > The plaintext API key is shown ONLY ONCE at creation time. Store it securely - it cannot be retrieved again.
 
@@ -306,22 +311,26 @@ For production deployments, see the [Database Prerequisites](../docs/content/ins
 
 #### Listing models with subscription filtering
 
-The `/v1/models` endpoint supports subscription filtering and aggregation:
+The `/v1/models` endpoint supports subscription filtering and aggregation. Use an **OpenShift token** or an **API key** in `Authorization: Bearer`. With a **user token**, optional `X-MaaS-Subscription` filters to one subscription when you have access to several. With an **API key**, the subscription is fixed at key mint time—no client `X-MaaS-Subscription` is needed for listing.
 
     HOST="$(kubectl get gateway -l app.kubernetes.io/instance=maas-default-gateway -n openshift-ingress -o jsonpath='{.items[0].status.addresses[0].value}')"
 
     # List models from all accessible subscriptions
     curl ${HOST}/v1/models \
         -H "Content-Type: application/json" \
-        -H "Authorization: Bearer $TOKEN" \
-        -H "X-MaaS-Return-All-Models: true" | jq .
+        -H "Authorization: Bearer $TOKEN" | jq .
 
     # List models from a specific subscription
     curl ${HOST}/v1/models \
         -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -H "X-MaaS-Subscription: my-subscription" | jq .
 
+    # List models from the subscription bound to an API key
+    curl ${HOST}/v1/models \
+        -H "Content-Type: application/json" \
+        -H "Authorization: Bearer $API_KEY" | jq .
+
 **Subscription Aggregation**: When the same model (same ID and URL) is accessible via multiple subscriptions, it appears once in the response with an array of all subscriptions providing access:
 
     {
@@ -340,14 +349,20 @@ The `/v1/models` endpoint supports subscription filtering and aggregation:
 
 #### Calling the model and hitting the rate limit
 
-Using model discovery:
+Inference requires an API key (mint with `POST /v1/api-keys` using your OpenShift token). Send **only** `Authorization: Bearer <api-key>`; subscription is taken from the key at mint time.
+
+Using model discovery (maas-api URL matches the [validation guide](../docs/content/install/validation.md); model `url` values come from the list response):
 
 ```shell
-HOST="$(kubectl get gateway -l app.kubernetes.io/instance=maas-default-gateway -n openshift-ingress -o jsonpath='{.items[0].status.addresses[0].value}')"
+CLUSTER_DOMAIN=$(kubectl get ingresses.config.openshift.io cluster -o jsonpath='{.spec.domain}')
+MAAS_API="https://maas.${CLUSTER_DOMAIN}/maas-api"
+API_KEY=$(curl -sSk -H "Authorization: Bearer $(oc whoami -t)" -H "Content-Type: application/json" \
+  -X POST -d '{"name":"rate-limit-demo","subscription":"simulator-subscription"}' \
+  "${MAAS_API}/v1/api-keys" | jq -r .key)
 
-MODELS=$(curl ${HOST}/v1/models  \
+MODELS=$(curl -sSk "${MAAS_API}/v1/models"  \
     -H "Content-Type: application/json" \
-    -H "Authorization: Bearer $TOKEN" | jq . -r)
+    -H "Authorization: Bearer ${API_KEY}" | jq . -r)
 
 echo $MODELS | jq .
 MODEL_URL=$(echo $MODELS | jq -r '.data[0].url')
@@ -356,7 +371,7 @@ MODEL_NAME=$(echo $MODELS | jq -r '.data[0].id')
 for i in {1..16}
 do
 curl -sSk -o /dev/null -w "%{http_code}\n" \
-  -H "Authorization: Bearer $TOKEN" \
+  -H "Authorization: Bearer ${API_KEY}" \
   -d "{
         \"model\": \"${MODEL_NAME}\",
         \"prompt\": \"Not really understood prompt\",

maas-controller/README.md

@@ -182,12 +182,16 @@ deny-unsubscribed (0):        matches "NOT in premium-user AND NOT in free-user"
 
 ## Authentication
 
-Until API token minting is in place, the controller uses **OpenShift tokens directly** for inference:
+Create API keys with `POST /v1/api-keys` on the maas-api (authenticate with your OpenShift token). Each key is bound to one MaaSSubscription at mint time: set `"subscription": "<name>"` in the JSON body, or omit it and the platform selects the **highest-priority** accessible subscription (`MaaSSubscription.spec.priority`).
 
 ```bash
-export TOKEN=$(oc whoami -t)
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://<gateway-host>/llm/<model-name>/v1/chat/completions" \
+MAAS_API="https://<gateway-host>/maas-api"
+API_KEY=$(curl -sSk -H "Authorization: Bearer $(oc whoami -t)" -H "Content-Type: application/json" \
+  -X POST -d '{"name":"demo","subscription":"<maas-subscription-name>"}' \
+  "${MAAS_API}/v1/api-keys" | jq -r .key)
+
+curl -sSk "https://<gateway-host>/llm/<model-name>/v1/chat/completions" \
+  -H "Authorization: Bearer ${API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{"model":"<model>","messages":[{"role":"user","content":"Hello"}],"max_tokens":10}'
 ```
@@ -289,22 +293,29 @@ kubectl get authpolicy,tokenratelimitpolicy -n llm
 
 # Test inference (set GATEWAY_HOST and TOKEN once)
 GATEWAY_HOST="maas.$(kubectl get ingresses.config.openshift.io cluster -o jsonpath='{.spec.domain}')"
+MAAS_API="https://${GATEWAY_HOST}/maas-api"
 TOKEN=$(oc whoami -t)
 
-# Regular model: 401 without auth, 200 with auth (user must be in free-user)
+# Regular tier: log in as a user in free-user, then mint a key for simulator-subscription
+FREE_API_KEY=$(curl -sSk -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -X POST -d '{"name":"readme-free","subscription":"simulator-subscription"}' \
+  "${MAAS_API}/v1/api-keys" | jq -r .key)
+
 curl -sSk -o /dev/null -w "%{http_code}\n" "https://${GATEWAY_HOST}/llm/facebook-opt-125m-simulated/v1/chat/completions" \
   -H "Content-Type: application/json" -d '{"model":"facebook/opt-125m","messages":[{"role":"user","content":"Hi"}],"max_tokens":5}'
 curl -sSk -o /dev/null -w "%{http_code}\n" "https://${GATEWAY_HOST}/llm/facebook-opt-125m-simulated/v1/chat/completions" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "x-maas-subscription: simulator-subscription" \
+  -H "Authorization: Bearer $FREE_API_KEY" \
   -H "Content-Type: application/json" -d '{"model":"facebook/opt-125m","messages":[{"role":"user","content":"Hi"}],"max_tokens":5}'
 
-# Premium model: 401 without auth, 200 with auth (user must be in premium-user)
+# Premium tier: log in as a user in premium-user, mint a key for premium-simulator-subscription, then call the premium route
+PREMIUM_API_KEY=$(curl -sSk -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -X POST -d '{"name":"readme-premium","subscription":"premium-simulator-subscription"}' \
+  "${MAAS_API}/v1/api-keys" | jq -r .key)
+
 curl -sSk -o /dev/null -w "%{http_code}\n" "https://${GATEWAY_HOST}/llm/premium-simulated-simulated-premium/v1/chat/completions" \
   -H "Content-Type: application/json" -d '{"model":"facebook/opt-125m","messages":[{"role":"user","content":"Hi"}],"max_tokens":5}'
 curl -sSk -o /dev/null -w "%{http_code}\n" "https://${GATEWAY_HOST}/llm/premium-simulated-simulated-premium/v1/chat/completions" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "x-maas-subscription: premium-simulator-subscription" \
+  -H "Authorization: Bearer $PREMIUM_API_KEY" \
   -H "Content-Type: application/json" -d '{"model":"facebook/opt-125m","messages":[{"role":"user","content":"Hi"}],"max_tokens":5}'
 ```