diff --git a/theolive/distribution/security/token-based-security.mdx b/theolive/distribution/security/token-based-security.mdx
index b533ec63f329..8abc772f2424 100644
--- a/theolive/distribution/security/token-based-security.mdx
+++ b/theolive/distribution/security/token-based-security.mdx
@@ -11,15 +11,80 @@ Token-based security restricts access to your stream by requiring a valid JWT (J
 
 ## How it works
 
-When token security is enabled on a distribution, the CDN validates an `Authorization` header containing a Bearer token on each request. The token is signed with a shared secret (HS256/HS512) or a public/private key pair (RS256/RS512) that you provide when enabling the feature.
+When token security is enabled on a distribution, the CDN validates the JWT on each request. The token is signed with a shared secret (HS256/HS512) or a public/private key pair (RS256/RS512) that you provide when enabling the feature.
+
+The token can be provided in one of two ways:
+
+- As an `Authorization` header with a Bearer token:
+
+  ```http
+  Authorization: Bearer <JWT>
+  ```
+
+- As a `token` query parameter:
+
+  ```
+  ?token=<JWT>
+  ```
 
 The token payload must include:
 
 - **`exp`** — expiration time in epoch format. The token is rejected after this time.
 - **`nbf`** _(optional)_ — "not before" time in epoch format. The token is rejected before this time.
 
+Additionally, the following standard optional claims are supported:
+
+| Claim | Type   | Description                                                                       |
+| ----- | ------ | --------------------------------------------------------------------------------- |
+| `sub` | string | Subject. If present, a SHA-256 hash of this value is used as the viewer identity. |
+| `iss` | string | Issuer. Identifies the system that created the token.                             |
+
 Requests without a valid token are rejected. If the distribution does not have token security enabled, the `Authorization` header is ignored.
 
+## Custom claims
+
+### The `optiview` claim
+
+The JWT token supports a custom `optiview` claim that enables fine-grained access control. When present, the claim restricts token usage based on channel, geography, or device type.
+
+| Property | Type                 | Description                                                                                                                                                                                                                                                                             |
+| -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ch`     | `string \| string[]` | Channel ID(s). If present, the token can exclusively be used for a channel in this list.                                                                                                                                                                                                |
+| `cc`     | `string \| string[]` | Country code(s) in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) format (e.g. `"US"`, `"BE"`). If present, the token can exclusively be used for a country in this list.                                                                                               |
+| `rgn`    | `string \| string[]` | Region code(s) using the subdivision codes defined in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) (e.g. `"US-CA"`, `"BE-VLG"`). If present, the token can exclusively be used for a region in this list. If the viewer's region cannot be determined, the request is denied. |
+| `hw`     | `string \| string[]` | Device type(s). If present, the token can exclusively be used by a device type in this list. Possible values: `"desktop"`, `"mobile"`, `"tv"`. If the viewer's device type cannot be determined, this restriction is skipped.                                                           |
+| `tid`    | string               | Tracking ID. A group identifier string used to correlate viewers.                                                                                                                                                                                                                       |
+| `cvd`    | string               | Custom viewer data. Arbitrary string attached to the session, e.g. an individual identifier to uniquely identify a viewer.                                                                                                                                                              |
+
+All properties are optional. When a property is omitted, no restriction is applied for that dimension.
+
+#### Device type mapping
+
+The `hw` device types are derived from the viewer's `User-Agent` header:
+
+| Detected device         | Mapped type |
+| ----------------------- | ----------- |
+| Desktop / Media player  | `desktop`   |
+| Smart Phone / Tablet    | `mobile`    |
+| Smart TV / Game console | `tv`        |
+
+**Example payload:**
+
+```json
+{
+  "sub": "user-12345",
+  "iat": 1516239022,
+  "exp": 1672531200,
+  "optiview": {
+    "ch": ["channel_1", "channel_2"],
+    "rgn": ["US-CA", "US-NY"],
+    "hw": ["mobile", "tv"],
+    "tid": "group-abc",
+    "cvd": "viewer-98765"
+  }
+}
+```
+
 ## Configuration
 
 To enable token-based security, navigate to your distribution's security settings and enable the token security toggle. Provide the shared secret or public key used to verify tokens.
@@ -30,9 +95,16 @@ To enable token-based security, navigate to your distribution's security setting
 
 </figure>
 
+## Supported signing algorithms
+
+| Algorithm family | Key type         | Description                            |
+| ---------------- | ---------------- | -------------------------------------- |
+| HS256 / HS512    | HMAC (symmetric) | Signed with a shared secret.           |
+| RS256 / RS512    | RSA (asymmetric) | Signed with a public/private key pair. |
+
 ## Player configuration
 
-The player needs to be configured to pass the `Authorization` header with each request. Refer to the platform-specific guides:
+The player needs to be configured to pass the token with each request. Refer to the platform-specific guides:
 
 - [Web](/theoplayer/how-to-guides/web/theolive/token-based-security/)
 - [Android](/theoplayer/how-to-guides/android/theolive/token-based-security/)