> ## Documentation Index > Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt > Use this file to discover all available pages before exploring further. # API Gateway v2 (HTTP/WebSocket) > API Gateway v2 (HTTP/WebSocket) APIs with Cloud Adapter. This page describes how API Gateway v2 (HTTP/WebSocket) maps to services in the environment where the application runs, including backend choices, supported operations and service-specific behavior. ## Supported environments * Azure * Google Cloud * OCI Check the operation and capability tables for the behavior your application depends on. A supported environment does not imply that every operation of the origin service is available. ## How the targets compare Each row compares a capability of API Gateway v2 (HTTP/WebSocket) with its adaptation on each target. A dash means this profile does not state the capability for that target. ### Cloud Adapter | Capability | API Gateway v2 (HTTP/WebSocket) | Azure, Google Cloud, and OCI · Tensor9 HTTP and WebSocket adapter on Envoy | Azure · Azure API Management | Google Cloud · Google Cloud API Gateway | | ---------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Which APIs are served here | Every API | Every API; the target an API resolves to unless a managed gateway's rule fits it entirely | An HTTP API whose every integration is HTTP\_PROXY or Lambda proxy; any authorizer kind | Only an API whose every route is JWT without scopes or NONE and whose every integration is HTTP\_PROXY or Lambda proxy | | Client protocols | HTTP and WebSocket | HTTP routes and worker-owned WebSocket connections | HTTP only; WebSocket APIs are served on Envoy | HTTP only; WebSocket APIs are served on Envoy | | Lambda proxy integration | Yes | Adapter-served - HTTP payload versions and WebSocket events are distinct | Adapter-served - Through the adapter's ingress, which holds the invocation authority | Adapter-served - Through the adapter's ingress, which holds the invocation authority | | Caller identity | Protocol-specific authorizers | JWT for HTTP; NONE, AWS\_IAM or REQUEST authorization for WebSocket connect | JWT and NONE decided by API Management; AWS\_IAM and Lambda authorizers decided by the adapter through a policy callout | JWT without scopes, checked by the gateway; NONE | | Lambda invocation permission | Function policy or integration role | Separate from caller admission and connection-management permission | Held by the adapter's ingress; API Management itself holds no AWS authority | Held by the adapter's ingress; the gateway itself holds no AWS authority | | Private HTTP integrations | Yes | No - This profile covers Lambda integrations only | Partial - An inbound private endpoint on Standard v2; VPC links are outside this contract | No - The gateway reaches integrations over public URLs | | Connection recovery | Application reconnects after disconnection | Reconnect and restore application state after socket-owner loss | Not applicable; WebSocket APIs are served on Envoy | Not applicable; WebSocket APIs are served on Envoy | | API coverage | full | partial (HTTP Lambda proxy requests and WebSocket connections; connection operations use the separate management API.) | partial (HTTP APIs that fit the eligibility rule; the management API is served for every API.) | partial (HTTP APIs that fit the eligibility rule; the management API is served for every API.) | ## On Azure, Google Cloud, and OCI ### Tensor9 HTTP and WebSocket adapter on Envoy | Capability | Area | Support | Operations | Notes | | ------------------------------ | ---- | -------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP JWT authorizers | - | Adapter-served | - | Checks issuer, audience, signing keys, token times and route scopes; JWT authorization is HTTP-only. | | HTTP Lambda authorizers | - | Adapter-served | - | Uses the selected event format and simple-response or IAM-policy mode with the configured identity sources and cache keys. | | HTTP Lambda proxy payloads | - | Adapter-served | - | Select payload format 1.0 or 2.0; event fields, cookies and repeated-header handling depend on that choice. | | Private WebSocket integrations | - | Out of scope | - | This mapping makes no private WebSocket integration or private frontend equivalence claim. | | WebSocket restart recovery | - | Partial | - | Clients reconnect and receive new connection identifiers after socket-owner loss; durable application state must live outside the connection. | | WebSocket route selection | - | Adapter-served | - | Selects connect, disconnect, default and message integrations; REQUEST authorization is applied at connection establishment. | | Operation | Area | Support | Depth | Notes | | ---------------- | --------------------- | -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | DeleteConnection | WebSocket connections | Adapter-served | Common | Disconnects the named connection after ManageConnections authorization; the client must reconnect for another session. | | GetConnection | WebSocket connections | Adapter-served | Common | Reads connection information through the API/stage management endpoint under the caller's own permission. | | PostToConnection | WebSocket connections | Adapter-served | Common | Sends bytes to an owned connection after ManageConnections authorization; a gone connection is refused, and acceptance is not client receipt. | #### HTTP APIs and WebSocket APIs The Tensor9 service adapter maps API Gateway v2 APIs to Envoy and adapter-owned API state in the target cluster. HTTP APIs route individual requests by method and path. WebSocket APIs establish a connection and then select integrations for connection events and messages. The protocol selected when creating the API determines which authorizers, events and integration settings apply. Management calls record routes, integrations, authorizers, deployments and stages. Envoy handles HTTP transport; a connection worker owns each accepted WebSocket. Backend integrations use their service adapters, including the Lambda adapter for function execution. Protocol Request path State held while serving HTTP Request → route and authorization → integration → response Stage configuration and one request WebSocket Connection authorization → socket owner → selected message integration Connection identifier and live socket #### HTTP events and authorizers HTTP Lambda proxy integrations select payload format `1.0` or `2.0`. The choice changes the function event and response contract, including cookies and repeated headers. Configure it explicitly and use a handler written for that format; a REST proxy handler is not automatically a format-2.0 handler. For an HTTP JWT authorizer, the adapter checks the configured issuer, audience, signing key, token times and route scopes. Lambda authorizers have separate format-1.0 and format-2.0 events. A simple Boolean response and an IAM-policy response are different configurations, with different cache and route-policy consequences. `AWS_IAM` uses target-environment credentials and an `execute-api:Invoke` decision. Public routes use `NONE`. Backend authorization is evaluated independently: allowing the caller does not grant the integration permission to invoke a function. The `AWS_PROXY` label alone does not identify a Lambda integration; other AWS-service subtypes are outside this profile's contract. #### WebSocket connection ownership WebSocket admission runs on `$connect`, using `NONE`, `AWS_IAM` or a REQUEST Lambda authorizer. HTTP JWT authorization does not apply to this handshake. Once accepted, the connection receives an identifier and remains attached to the worker holding its socket. Message routes and `$default` select integrations using the configured route-selection expression. The connection identifier is not a portable session. If its worker stops, clients reconnect, pass admission again and receive a new identifier. Applications must handle a missed `$disconnect` notification and must not use that event as their only cleanup mechanism. `PostToConnection`, `GetConnection` and `DeleteConnection` use a management endpoint scoped to the API and stage. The application making these calls authenticates separately from the connected client and needs the relevant `execute-api:ManageConnections` permission. A connection identifier by itself grants no permission. Sending to an absent connection returns a gone response; acceptance of a send is not an acknowledgement from the remote application. #### Deployment changes and connectivity HTTP stages can select explicit deployments or use auto-deploy. This profile requires explicit deployments for WebSocket configuration. The adapter keeps the API configuration in durable storage, but a durable configuration record cannot recreate an open socket after worker loss. For a change that must affect every WebSocket client, disconnect and reconnect those clients after deploying the stage. This profile does not promise immediate application of changed route policies, integration settings or credential revocation to existing connections. Public client access and private backend access are configured separately. An HTTP VPC link reaches a private HTTP integration; it does not create a private HTTP or WebSocket frontend. Lambda integrations use the Lambda adapter and need no VPC link. Private HTTP and WebSocket integrations and AWS endpoint-identity policy conditions are outside this profile's connectivity contract. #### Limitations △ Differences to review before moving an HTTP or WebSocket API * **HTTP and WebSocket authorizers differ.** JWT authorization belongs to HTTP APIs. WebSocket REQUEST authorization runs at connection establishment; applications needing per-message user authorization must enforce it in their message handlers. * **Open connections do not survive owner loss.** Reconnect with application-level recovery for subscriptions, delivery positions and unfinished work. This mapping does not provide transparent socket migration or exactly-once message delivery. * **Policy changes require a connection policy.** Use explicit disconnection where an existing session must lose access. Do not assume a stage deployment immediately reauthorizes every connected client. * **Additional API Gateway products are excluded.** Portal and product publishing, non-Lambda AWS-service integration subtypes, private WebSocket integrations and private frontend equivalence are not part of this profile. #### Other considerations * **Migration.** Recreate APIs and backend permissions, configure target credentials and certificates, then switch HTTP endpoints or reconnect WebSocket clients. Connection identifiers from AWS cannot address sockets in the target environment. * **Operation.** Tensor9 maintains the service adapter and connection-management behavior. The target platform supplies gateway compute, durable configuration storage, networking and TLS termination. Restrict internal worker and authorization endpoints to the serving components. * **Application recovery.** Store durable subscription or workflow state in the application, outside the live socket. Give retried messages application identifiers and acknowledge them at the application level when delivery matters. * **Capacity.** Track concurrent connections, message sizes, slow-client queues and integration concurrency separately. An HTTP request rate is not a capacity estimate for long-lived WebSocket connections. ## On Azure ### Azure API Management | Capability | Area | Support | Operations | Notes | | ------------------------- | ---- | -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AWS\_IAM authorization | - | Adapter-served | - | A policy on the operation sends the request's signature to the adapter, which verifies the SigV4 credential and evaluates execute-api:Invoke before the backend is reached. Each such request makes that callout. | | Eligibility rule | - | Partial | - | An HTTP API is served here when every integration is an HTTP\_PROXY to a URL or a Lambda proxy. Any of the four authorizer kinds is accepted. An API outside the rule is refused when the ineligible route or integration is created and is served on Envoy as a whole. | | HTTP proxy integrations | - | Supported | - | Each route becomes an API Management operation whose backend is the integration URL; the response is returned as the backend sent it. | | JWT authorizers | - | Supported | - | Issuer, audience, signing keys, token times and required scopes are checked by an API Management validate-jwt policy on the operation. | | Lambda authorizers | - | Adapter-served | - | A policy on the operation calls the adapter, which runs the authorizer with the configured identity sources and cache keys and returns the decision. Each such request makes that callout unless cached. | | Lambda proxy integrations | - | Adapter-served | - | The operation's backend is the adapter's ingress, which builds the payload format 1.0 or 2.0 event and invokes the function under the integration's own authority. | | Public routes (NONE) | - | Supported | - | Served as operations with no authorization policy. | | WebSocket APIs | - | Out of scope | - | A WebSocket API is served on Envoy, where the adapter's connection worker owns the socket. | #### How an API lands on Azure API Management Your tooling calls the API Gateway v2 management API unchanged. The adapter records the API, its routes, integrations, authorizers, deployments and stages, and when a stage is deployed it writes an API Management API with one operation per route and method, each carrying the policies its authorization needs and a backend pointing at the integration. Requests from your clients go to the API Management hostname and are handled by Azure. The decision to use this target is made once per API. Every route, authorizer and integration is checked against the rule below as it is created, and an API that fits is served here in full. An API that does not fit is served on Envoy in full; routes are never split between the two backends. #### The eligibility rule Azure API Management serves an HTTP API when every integration is an HTTP\_PROXY to a URL, or a Lambda proxy (AWS\_PROXY) reached through the adapter's ingress. Any of the four authorizer kinds is accepted: NONE and JWT are decided by API Management's own policies, and AWS\_IAM and Lambda authorizers are decided by the adapter through a policy callout on each request. A WebSocket API is outside the rule and is served on Envoy. A CreateRoute, CreateAuthorizer or CreateIntegration outside the rule is refused when it is made, with the reason. #### Authorizers and the callout A JWT authorizer becomes a validate-jwt policy on each of its operations: issuer, audience, signing keys, token times and required scopes are checked by API Management. A public route has no authorization policy. An AWS\_IAM route or a route with a Lambda authorizer carries a policy that sends the request's identity material to the adapter before the backend is called. For AWS\_IAM the adapter verifies the SigV4 signature and evaluates execute-api:Invoke against the caller's permissions; for a Lambda authorizer it runs your authorizer function with the configured identity sources and honours its cache settings. A deny is returned to the client as API Gateway would return it, and the backend is not reached. The callout is a network hop on every such request, so an AWS\_IAM or Lambda-authorizer route on this target has higher latency than the same route on Envoy, where the check is in-cluster. #### Integrations, deployments and stages An HTTP\_PROXY integration becomes the operation's backend URL. A Lambda proxy integration's backend is the adapter's ingress, which builds the payload format 1.0 or 2.0 event, invokes the function under the integration's own authority and returns the function's status, headers and body; API Management holds no AWS credential and cannot invoke a function itself. A deployment records a fixed revision of the API and a stage selects one. A stage change is a set of operation and policy writes on API Management, applied together; propagation is a matter of seconds, not the minutes of an API config rollout. Exercise a route after deploying before moving traffic. #### Limitations * **WebSocket APIs are not served here.** They are served on Envoy, where the adapter's connection worker owns the socket. - **AWS\_IAM and Lambda-authorizer routes cost a callout.** Each such request makes a synchronous call to the adapter before the backend; measure the added latency for your routes before choosing this target for a latency-sensitive API. - **One operation per route and method.** A route key with ANY becomes one operation per HTTP method, and the policy document that decides eligibility grows with the route count; a very large API may exceed API Management's policy size limit and is refused with the reason. - **API Management reaches backends over HTTP/1.1.** There is no HTTP/2 from the gateway to the backend. - **Custom domains and certificates are configured on API Management**, not through the API Gateway v2 domain-name calls. #### Other considerations * **Operations and ownership.** Azure runs API Management; the adapter owns your API configuration, the authorization callouts and the Lambda ingress. Gateway capacity, request logs and metrics are Azure's, and the Standard v2 tier is the one this mapping provisions. - **Private ingress.** Standard v2 supports an inbound private endpoint, so the gateway can be made reachable only through your network; configure that on API Management. - **Choosing between the two targets.** Pick this target when you want Azure to run the request path and your authorizer mix is mostly JWT or public. An API whose routes are mostly AWS\_IAM or Lambda-authorized keeps lower latency on Envoy. - **Migration.** Recreate the API, deploy a stage, confirm the API Management hostname answers, then repoint clients or DNS. ## On Google Cloud ### Google Cloud API Gateway | Capability | Area | Support | Operations | Notes | | ------------------------------- | ---- | -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AWS\_IAM and Lambda authorizers | - | Out of scope | - | Google Cloud API Gateway cannot evaluate a SigV4 signature or run a Lambda authorizer. An API that uses either is served on Envoy. | | Eligibility rule | - | Partial | - | An API is served here only when every route is JWT without scopes or NONE and every integration is an HTTP\_PROXY to a URL or a Lambda proxy. A CreateRoute, CreateAuthorizer or CreateIntegration outside that rule is refused when it is made, and the API is served on Envoy as a whole; routes are never split between the two. | | HTTP proxy integrations | - | Supported | - | Each route forwards to its integration URL; Google Cloud API Gateway returns the backend's status, headers and body. | | JWT authorizers without scopes | - | Supported | - | Issuer, audience, signing keys and token times are checked by the gateway. A JWT authorizer that requires route scopes is outside this target's rule. | | Lambda proxy integrations | - | Adapter-served | - | The gateway forwards to the adapter's ingress, which builds the payload format 1.0 or 2.0 event and invokes the function under the integration's own authority. | | Public routes (NONE) | - | Supported | - | Served as public gateway routes. | | WebSocket APIs | - | Out of scope | - | Google Cloud API Gateway serves HTTP APIs only. A WebSocket API is served on Envoy. | #### How an API lands on Google Cloud API Gateway Your tooling calls the API Gateway v2 management API unchanged. The adapter records the API, its routes, integrations, authorizers, deployments and stages, and when a stage is deployed it renders that stage as an OpenAPI document, creates a Google Cloud API Gateway API config from it and points a gateway at the config. Requests from your clients go to the gateway's hostname and are handled by Google; the adapter is not on the request path. The decision to use this target is made once per API. Every route, authorizer and integration is checked against the rule below as it is created, and an API that fits is served here in full. An API that does not fit is served on Envoy in full. Routes are never split between the two backends, because a custom domain has one DNS target and every API mapped under it must resolve the same way. #### The eligibility rule Google Cloud API Gateway serves an API when: * every route's authorization is a JWT authorizer with no required scopes, or NONE; and - every integration is an HTTP\_PROXY to a URL, or a Lambda proxy (AWS\_PROXY) reached through the adapter's ingress. A route with AWS\_IAM authorization, a Lambda authorizer, or a JWT authorizer that requires scopes takes the API outside the rule, because the gateway cannot evaluate a SigV4 signature, run your authorizer function, or check scopes. A CreateRoute, CreateAuthorizer or CreateIntegration outside the rule is refused when it is made, with the reason, rather than accepted and served differently. #### Authorizers and integrations For a JWT authorizer the gateway checks issuer, audience, signing keys and token times against the configured identity provider, and passes the verified claims to the backend. A public route (NONE) is served without a check. An HTTP\_PROXY integration forwards the request to the integration URL and returns the backend's response. A Lambda proxy integration forwards to the adapter's ingress, which builds the payload format 1.0 or 2.0 event, invokes the function under the integration's own authority and returns the function's status, headers and body; the gateway holds no AWS credential and cannot invoke a function itself. #### Deployments and stages A deployment records a fixed revision of the API; a stage selects one. Each stage change becomes a new API config and a gateway update, and Google Cloud propagates a config change over minutes rather than seconds, so a stage update is a rollout rather than an instant switch. Deploy the stage, wait for the gateway to report the new config, and exercise the route before moving traffic. #### Limitations * **The rule is the boundary.** AWS\_IAM routes, Lambda authorizers, JWT scopes and WebSocket APIs are not expressible on Google Cloud API Gateway; an API that uses any of them is served on Envoy in full. - **Config changes propagate over minutes.** A stage update is an API config rollout on Google's side; plan cutovers around that, and do not treat CreateStage's response as serving readiness. - **Integrations are reached over public URLs.** The gateway does not join your network; a private backend needs its own exposure, and VPC links are outside this contract. - **The gateway hostname is Google's.** Custom domains and certificates are configured on Google Cloud, not through the API Gateway v2 domain-name calls. #### Other considerations * **Operations and ownership.** Google Cloud runs the gateway; the adapter owns your API configuration and the Lambda ingress. Gateway quotas, request logs and metrics are Google's. - **Choosing between the two targets.** If any API you deploy needs AWS\_IAM or a Lambda authorizer, the Envoy target serves everything and keeps one operating model. Pick this target when your APIs are JWT or public and you want Google to run the request path. - **Migration.** Recreate the API, deploy a stage, confirm the gateway's hostname answers, then repoint clients or DNS. ## Existing data and credentials Selecting a backend does not copy existing data, credentials or access policies. Plan and verify migration separately before changing an application's endpoint. Do not assume an identifier, credential or encrypted value from the origin service works unchanged on the target. ## Configure, tune and debug Start with [setup](/cloud-adapter/getting-started/overview) and [configuration](/cloud-adapter/configuration/overview). Use [tuning](/cloud-adapter/tuning/overview) to understand supported request tags, [debugging](/cloud-adapter/debugging/overview) to investigate a request, and [High Fidelity Cloud Emulators](/cloud-adapter/local-testing/overview) to validate a bounded reproduction. For requests that go through the service adapter, use [tensor9 explain](/cloud-adapter/debugging/explain) and [x-t9-explain](/cloud-adapter/debugging/response-headers) to inspect the selected mapping.