> ## Documentation Index > Fetch the complete documentation index at: https://docs.agg.market/llms.txt > Use this file to discover all available pages before exploring further. # Auth > Authenticate mid-session to receive user-specific events. Send your JWT token (same as REST API) to upgrade from app-level to user-level auth. Supports re-authentication for token refresh or user switch. **Connect-time auth:** Pass `?token=eyJ...` as a query param alongside `appId`. ## AsyncAPI ````yaml openapi/asyncapi.json auth id: auth title: Auth description: >- Authenticate mid-session to receive user-specific events. Send your JWT token (same as REST API) to upgrade from app-level to user-level auth. Supports re-authentication for token refresh or user switch. **Connect-time auth:** Pass `?token=eyJ...` as a query param alongside `appId`. servers: - id: production protocol: wss host: ws.agg.market bindings: [] variables: [] address: / parameters: [] bindings: [] operations: - &ref_4 id: authenticate title: Authenticate description: Authenticate mid-session with JWT for user-level events type: send messages: - &ref_8 id: authenticate payload: - name: Authenticate user mid-session description: >- Upgrade connection to user-level auth. Uses the same JWT as the REST API. Supports re-authentication for token refresh or user switch. type: object properties: - name: action type: string description: authenticate required: true - name: token type: string description: JWT token for user-level auth (same token used for REST API) required: true headers: [] jsonPayloadSchema: title: Authenticate type: object required: - action - token properties: action: const: authenticate type: string x-parser-schema-id: token: description: JWT token for user-level auth (same token used for REST API) type: string x-parser-schema-id: x-parser-schema-id: title: Authenticate user mid-session description: >- Upgrade connection to user-level auth. Uses the same JWT as the REST API. Supports re-authentication for token refresh or user switch. example: |- { "action": "authenticate", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } bindings: [] extensions: - id: x-parser-unique-object-id value: authenticate bindings: [] extensions: &ref_0 - id: x-parser-unique-object-id value: auth - &ref_1 id: receiveConnected title: Receive connected description: Connection acknowledgement (sent immediately on connect) type: receive messages: - &ref_5 id: connected payload: - name: Connection acknowledged description: >- Sent immediately after successful connection. Includes userId if JWT was provided on connect. type: object properties: - name: type type: string description: connected required: true - name: appId type: string required: true - name: userId type: string required: false headers: [] jsonPayloadSchema: title: Connected type: object required: - type - appId properties: type: const: connected type: string x-parser-schema-id: appId: type: string x-parser-schema-id: userId: type: string x-parser-schema-id: x-parser-schema-id: title: Connection acknowledged description: >- Sent immediately after successful connection. Includes userId if JWT was provided on connect. example: |- { "type": "connected", "appId": "app_demo123", "userId": "usr_xyz789" } bindings: [] extensions: - id: x-parser-unique-object-id value: connected bindings: [] extensions: *ref_0 - &ref_2 id: receiveAuthenticated title: Receive authenticated description: User authentication confirmation type: receive messages: - &ref_6 id: authenticated payload: - name: User authenticated description: Confirms successful mid-session authentication type: object properties: - name: type type: string description: authenticated required: true - name: userId type: string required: true headers: [] jsonPayloadSchema: title: Authenticated type: object required: - type - userId properties: type: const: authenticated type: string x-parser-schema-id: userId: type: string x-parser-schema-id: x-parser-schema-id: title: User authenticated description: Confirms successful mid-session authentication example: |- { "type": "authenticated", "userId": "usr_xyz789" } bindings: [] extensions: - id: x-parser-unique-object-id value: authenticated bindings: [] extensions: *ref_0 - &ref_3 id: receiveHeartbeat title: Receive heartbeat description: Application-level heartbeat event type: receive messages: - &ref_7 id: heartbeat payload: - name: Heartbeat description: Application-level heartbeat event for connection liveness type: object properties: - name: type type: string description: heartbeat required: true - name: ts type: number description: Server timestamp in milliseconds required: true headers: [] jsonPayloadSchema: title: Heartbeat type: object required: - type - ts properties: type: const: heartbeat type: string x-parser-schema-id: ts: description: Server timestamp in milliseconds type: number x-parser-schema-id: x-parser-schema-id: title: Heartbeat description: Application-level heartbeat event for connection liveness example: |- { "type": "heartbeat", "ts": 1710000000000 } bindings: [] extensions: - id: x-parser-unique-object-id value: heartbeat bindings: [] extensions: *ref_0 sendOperations: - *ref_1 - *ref_2 - *ref_3 receiveOperations: - *ref_4 sendMessages: - *ref_5 - *ref_6 - *ref_7 receiveMessages: - *ref_8 extensions: - id: x-parser-unique-object-id value: auth securitySchemes: - id: appId name: appId type: userPassword description: >- App-level auth: pass appId as a query parameter on connect. Required for all connections. The appId must belong to an active app with matching allowed origins. extensions: [] - id: jwt name: jwt type: http description: >- User-level auth: pass JWT as token query param on connect, or send { action: 'authenticate', token } mid-session. Required for user-specific events (orders, balances). Same JWT as the REST API. scheme: bearer bearerFormat: JWT extensions: [] ````