Merged main into the branch

Signed-off-by: Dmytro Zaharnytskyi <zdmytro@redhat.com>

Author: dmytro-zaharnytskyi

deployment/base/maas-api/policies/auth-policy.yaml

@@ -82,3 +82,12 @@ spec:
               selector: auth.identity.user.groups.@tostr
             key: X-MaaS-Group
             priority: 1
+          # Subscription: from API key validation (when API key with subscription used)
+          # This header is used by /v1/models to determine which subscription's models to return
+          X-MaaS-Subscription:
+            when:
+              - predicate: request.headers.authorization.startsWith("Bearer sk-oai-")
+              - predicate: auth.metadata.apiKeyValidation.subscription != ""
+            plain:
+              selector: auth.metadata.apiKeyValidation.subscription
+            priority: 0

docs/content/architecture.md

@@ -57,39 +57,55 @@ If the API is not configured with a MaaSModelRef lister and namespace, or if lis
 
 ## Subscription Filtering and Aggregation
 
-The `/v1/models` endpoint supports filtering and aggregating models across subscriptions using request headers.
+The `/v1/models` endpoint automatically filters models based on your authentication method and optional headers.
 
-### Request Headers
+### Authentication-Based Behavior
 
-- **`X-MaaS-Subscription`** (optional): Filter models to a specific subscription by name
-- **`X-MaaS-Return-All-Models`** (optional): When set to `"true"`, returns models from all subscriptions the user has access to
+#### 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**
 
-!!! warning "Conflicting headers"
-    You cannot specify both `X-MaaS-Subscription` and `X-MaaS-Return-All-Models` headers in the same request. This returns `400 Bad Request`.
+```bash
+# API key bound to "premium-subscription"
+curl -H "Authorization: Bearer sk-oai-abc123..." \
+     https://maas.example.com/maas-api/v1/models
 
-### Behavior Modes
+# Returns models from "premium-subscription" only
+```
 
-#### Default (no header)
-Returns models from a single subscription:
-- If the user has access to only one subscription, models from that subscription are returned
-- If the user has access to multiple subscriptions, returns `403 Forbidden` with message: "user has access to multiple subscriptions, must specify subscription using X-MaaS-Subscription header"
+#### User Token Authentication (OpenShift/OIDC tokens)
+When using a user token, you have flexible options:
+
+**Default (no X-MaaS-Subscription header)**:
+- Returns **all** models from all subscriptions you have access to
+- Models are deduplicated and subscription metadata is attached
 
-#### Single Subscription (`X-MaaS-Subscription: <name>`)
-Returns only models accessible via the specified subscription:
 ```bash
-curl -H "Authorization: Bearer $TOKEN" \
-     -H "X-MaaS-Subscription: premium-subscription" \
+# User with access to "basic" and "premium" subscriptions
+curl -H "Authorization: Bearer $(oc whoami -t)" \
      https://maas.example.com/maas-api/v1/models
+
+# Returns models from both subscriptions with subscription metadata
 ```
 
-#### All Subscriptions (`X-MaaS-Return-All-Models: true`)
-Returns models from all subscriptions the user has access to, with subscription metadata attached. If the user has access to zero subscriptions, returns HTTP 200 with an empty data array (not an error), allowing clients to handle this deterministically:
+**With X-MaaS-Subscription header** (optional):
+- Returns only models from the specified subscription
+- Behaves like an API key request - allows you to scope your query to a specific subscription
+
 ```bash
-curl -H "Authorization: Bearer $TOKEN" \
-     -H "X-MaaS-Return-All-Models: true" \
+# Filter to only "premium" subscription models
+curl -H "Authorization: Bearer $(oc whoami -t)" \
+     -H "X-MaaS-Subscription: premium-subscription" \
      https://maas.example.com/maas-api/v1/models
+
+# Returns only "premium-subscription" models
 ```
 
+!!! tip "User token filtering"
+    The `X-MaaS-Subscription` header allows user token requests to filter results to a specific subscription. This is useful when you have access to many subscriptions but only want to see models from one.
+
 ### Subscription Metadata
 
 All models in the response include a `subscriptions` array with metadata for each subscription providing access to that model:
@@ -124,16 +140,22 @@ All models in the response include a `subscriptions` array with metadata for eac
 
 ### Deduplication Behavior
 
-When `X-MaaS-Return-All-Models: true` is used, models are deduplicated by `(id, url)` key:
+Models are deduplicated by `(id, url, ownedBy)` key:
 
-- **Same id + same URL**: Single entry with subscriptions aggregated into the `subscriptions` array
-- **Same id + different URLs**: Separate entries (different model endpoints)
+- **Same id + same URL + same MaaSModelRef (ownedBy)**: Single entry with subscriptions aggregated into the `subscriptions` array
+- **Different id, URL, or MaaSModelRef**: Separate entries
 
-**Example:**
-- Model `gpt-3.5` at URL `https://example.com/gpt-3.5` is accessible via subscriptions A and B
+**User token authentication** (multiple subscriptions):
+- Model `gpt-3.5` from MaaSModelRef `namespace-a/model-a` at URL `https://example.com/gpt-3.5` is accessible via subscriptions A and B
   - Result: One entry with `subscriptions: [{name: "A"}, {name: "B"}]`
-- Model `gpt-3.5` at URL `https://example.com/gpt-3.5-premium` is only in subscription B
-  - Result: Separate entry with `subscriptions: [{name: "B"}]`
+- Model `gpt-3.5` from MaaSModelRef `namespace-b/model-b` at the same URL is only in subscription B
+  - Result: Separate entry with `subscriptions: [{name: "B"}]` (different MaaSModelRef)
+- Model `gpt-3.5` at URL `https://example.com/gpt-3.5-premium` from `namespace-a/model-a` is only in subscription B
+  - Result: Separate entry with `subscriptions: [{name: "B"}]` (different URL)
+
+**API key authentication** (single subscription):
+- Deduplication handles edge cases where multiple MaaSModelRef resources point to the same model endpoint
+- Each unique MaaSModelRef resource appears as a separate entry
 
 !!! tip "Subscription metadata fields"
     The `displayName` and `description` fields are read from the MaaSSubscription CRD's `spec.displayName` and `spec.description` fields. If these fields are not set in the CRD, they will be empty strings in the response.

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

@@ -121,6 +121,7 @@ spec:
       tokenRateLimits:
         - limit: 100
           window: 1m
+  priority: 10
 EOF
 ```
 
@@ -162,6 +163,7 @@ spec:
       tokenRateLimits:
         - limit: 100000
           window: 24h
+  priority: 20
   tokenMetadata:
     organizationId: "premium-org"
     costCenter: "ai-team"
@@ -216,20 +218,7 @@ Users will get subscription access on their next request (after group membership
 
 ## Multiple Subscriptions per User
 
-When a user belongs to multiple groups that each have a subscription:
-
-1. **Single subscription** — No `X-MaaS-Subscription` header needed
-2. **Multiple subscriptions** — Client **must** send `X-MaaS-Subscription: <subscription-name>` to specify which subscription's rate limits apply
-
-Example for a user in both `free-users` and `premium-users`:
-
-```bash
-# Use free subscription limits
-curl -H "X-MaaS-Subscription: free-subscription" ...
-
-# Use premium subscription limits
-curl -H "X-MaaS-Subscription: premium-subscription" ...
-```
+When a user belongs to multiple groups that each have a subscription, the access depends on the API key used. A subscription is bound to each API key at minting (explicit or highest priority). See [Understanding Token Management](token-management.md).
 
 ## Troubleshooting
 

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

@@ -2,32 +2,6 @@
 
 This document describes known issues and operational considerations for the subscription-based MaaS Platform.
 
-## X-MaaS-Subscription Header
-
-### Multiple Subscriptions Require Header
-
-**Impact:** High
-
-**Description:**
-
-When a user belongs to multiple groups that each have a MaaSSubscription, the client **must** send the `X-MaaS-Subscription` header to specify which subscription's rate limits apply. If the header is omitted, the MaaS API returns an error and the request is denied with **403 Forbidden**.
-
-**Example:**
-
-```text
-User in groups: [system:authenticated, premium-users]
-Subscriptions: free-subscription (system:authenticated), premium-subscription (premium-users)
-
-Request without header → 403 "must specify X-MaaS-Subscription"
-Request with X-MaaS-Subscription: premium-subscription → 200 OK (premium limits apply)
-```
-
-**Workaround:**
-
-- Ensure clients send `X-MaaS-Subscription: <subscription-name>` when users can have multiple subscriptions
-- Document which subscription names to use for each user segment
-- Consider using a single subscription per user segment to avoid header requirement
-
 ## Subscription Selection Caching
 
 ### Cache TTL for Subscription Selection
@@ -55,11 +29,11 @@ Authorino caches the result of the MaaS API subscription selection call (e.g., 6
 
 **Description:**
 
-API keys store the user's groups at creation time. If a user's group membership changes after the key was created:
+API keys store the user's groups and bound subscription name at creation time. If a user's group membership changes after the key was created:
 
-- The key still carries the **old** groups until it is revoked and recreated
-- Subscription selection uses the groups from the key validation response (the stored snapshot)
-- The user must create a new API key to get updated group membership and subscription access
+- The key still carries the **old** groups and subscription until it is revoked and recreated
+- Subscription metadata for gateway inference uses the stored groups and subscription from validation
+- The user must create a new API key to pick up new groups or a different default subscription
 
 **Workaround:**
 
@@ -68,5 +42,6 @@ API keys store the user's groups at creation time. If a user's group membership
 
 ## Related Documentation
 
+- [Understanding Token Management](token-management.md)
 - [Access and Quota Overview](subscription-overview.md)
 - [Quota and Access Configuration](quota-and-access-configuration.md)