Managing connected users and client apps: $connect and $disconnect routes - Amazon API Gateway
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Managing connected users and client apps: $connect and $disconnect routes

The $connect route

Client apps connect to your WebSocket API by sending a WebSocket upgrade request. If the request succeeds, the $connect route is executed while the connection is being established.

Because the WebSocket connection is a stateful connection, you can configure authorization on the $connect route only. AuthN/AuthZ will be performed only at connection time.

Until execution of the integration associated with the $connect route is completed, the upgrade request is pending and the actual connection will not be established. If the $connect request fails (e.g., due to AuthN/AuthZ failure or an integration failure), the connection will not be made.


If authorization fails on $connect, the connection will not be established, and the client will receive a 401 or 403 response.

Setting up an integration for $connect is optional. You should consider setting up a $connect integration if:

  • You want to enable clients to specify subprotocols by using the Sec-WebSocket-Protocol field. For example code, see Setting up a $connect route that requires a WebSocket subprotocol.

  • You want to be notified when clients connect and disconnect.

  • You want to throttle connections or control who connects.

  • You want your backend to send messages back to clients using a callback URL.

  • You want to store each connection ID and other information into a database (for example, Amazon DynamoDB).

The $disconnect route

The $disconnect route is executed after the connection is closed.

The connection can be closed by the server or by the client. As the connection is already closed when it is executed, $disconnect is a best-effort event. API Gateway will try its best to deliver the $disconnect event to your integration, but it cannot guarantee delivery.

The backend can initiate disconnection by using the @connections API. For more information, see Use @connections commands in your backend service.