ai-transport/sessions-identity: add identity

Describes how identity relates to session management and how this works
in the context of channel-oriented sessions.

Author: mschristensen

src/pages/docs/ai-transport/sessions-identity/overview.mdx

@@ -3,7 +3,7 @@ title: "Sessions & identity overview"
 meta_description: "Manage session lifecycle and identity in decoupled AI architectures"
 ---
 
-When building AI applications with Ably AI Transport, session management works differently than in traditional HTTP streaming architectures. Sessions persist beyond individual connections, enabling agents and clients to connect independently through shared channels.
+Ably AI Transport provides robust session management and identity capabilities designed for modern AI applications. Sessions persist beyond individual connections, enabling agents and clients to connect independently through shared channels. Built-in token-based authentication provides verified user identity and fine-grained authorization for channel operations.
 
 ## What is a session?
 
@@ -52,3 +52,14 @@ The following table compares how each architecture addresses the engineering cha
 | **Message resume** | Agents must buffer sent messages and implement replay logic. When clients reconnect, agents must determine what was missed and retransmit without duplicates or gaps, distinctly for each connection. | When clients reconnect, they automatically receive messages published while disconnected. The channel maintains history without agents implementing buffering or replay logic, eliminating the need for server-side session state. |
 | **Abandonment detection** | Agents must implement logic to distinguish between brief network interruptions and users who have actually left, so they can decide whether to continue work or clean up resources. | Built-in presence tracking signals when users enter and leave channels, providing clear lifecycle events to agents without custom detection logic. |
 | **Multi-user and multi-device** | Agents must manage multiple concurrent connections from the same user across devices, or from multiple users in collaborative sessions. This requires tracking connections, synchronizing state, and ensuring all participants receive consistent updates. | Multiple users and devices can connect to the same channel. The channel handles message delivery to all participants, simplifying agent logic for multi-user and multi-device scenarios. |
+
+## Identity in channel-oriented sessions
+
+In connection-oriented architectures, the agent server handles authentication directly when establishing the connection. When the connection is opened, the server verifies credentials and associates the authenticated user identity with that specific connection.
+
+In channel-oriented sessions, agents don't manage connections or handle authentication directly. Instead, your server authenticates users and issues tokens that control their access to channels. Ably enforces these authorization rules and provides verified identity information to agents, giving you powerful capabilities for managing who can participate in sessions and what they can do:
+
+- **Verified identity**: Agents automatically receive the authenticated identity of message senders, with cryptographic guarantees that identities cannot be spoofed
+- **Granular authorization**: Control precisely what operations each user can perform on specific channels through fine-grained capabilities
+- **Rich user attributes**: Pass authenticated user data to agents for personalized behavior without building custom token systems
+- **Role-based participation**: Distinguish between different types of participants, such as users and agents, to customize behaviour based on their role