> For the complete documentation index, see [llms.txt](https://docs.bosonnetwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bosonnetwork.io/core-concepts/services/web-gateway.md).

# Web Gateway

The **Web Gateway** is a Boson Layer-2 service that runs on a super node and exposes the Boson DHT as an authenticated HTTPS API. It bridges the gap between the UDP-only DHT protocol and HTTP-only clients - web browsers, serverless functions, and other restricted environments - so they can participate fully in the Boson network without running a UDP DHT stack of their own.

It is the service that makes the **Light Node** role possible. Boson defines three node roles, distinguished by how they reach the DHT:

| Node type        | DHT access                 | Service access         | Typical use                                             |
| ---------------- | -------------------------- | ---------------------- | ------------------------------------------------------- |
| **Super Node**   | Full DHT (UDP)             | Hosts Layer-2 services | Server infrastructure                                   |
| **Regular Node** | Full DHT (UDP)             | Consumes services      | Native desktop / mobile apps                            |
| **Light Node**   | None - via the Web Gateway | Consumes services      | Apps that do not run a DHT node, including browser apps |

A Light Node holds an Ed25519 key, signs a CWT, and makes ordinary HTTPS calls to a Web Gateway; the gateway performs the corresponding DHT operations on its behalf and returns the results as JSON.

***

## Features

* **DHT-over-HTTP bridge** - translates REST calls into `FIND_NODE`, `FIND_VALUE`, `STORE_VALUE`, `FIND_PEER`, and `ANNOUNCE_PEER` operations on the live DHT.
* **Authenticated** - every request must carry a CBOR Web Token (CWT) from a user or device registered on the super node; anonymous DHT access is not permitted.
* **Rate-limited** - per-user, per-address and service-wide limits protect the gateway; plans can raise the per-user limits.
* **Lookup-mode ceiling** - operators cap how thorough a DHT lookup a user may request (`maxLookupOption`).
* **CORS-enabled** - response headers permit cross-origin requests from any browser origin.
* **TLS** - with the node's certificate, from a public authority or self-signed and bound to the node's identity.
* **DHT-announced** - the service registers itself as a peer so Light Nodes discover it automatically via `FIND_PEER`.

***

## Configuration

The service type is `io.bosonnetwork.webgateway`. As shipped:

```yaml
host: 0.0.0.0
port: 9001
ssl: true

dht:
  defaultLookupOption: OPTIMISTIC
  defaultTimeout: 30s
  maxConcurrentRequests: 512

limits:
  user:
    maxLookupOption: OPTIMISTIC
    maxPersistentValues: 16
    maxPersistentPeers: 16
    rateLimit:
      perMinute: 16
      perHour: 64
      perDay: 512
```

* `limits.user.maxLookupOption` caps how thorough a lookup a user may ask for.
* `maxPersistentValues` and `maxPersistentPeers` bound the records the gateway keeps alive for each user.
* `dht.maxConcurrentRequests` bounds DHT work in flight; requests beyond it are refused with `503`.

See [Configuring Services](/configure-a-node/services-config.md#web-gateway) and the [Configuration Reference](/reference/configuration.md#web-gateway).

***

## HTTP API

The endpoints, request and response formats, lookup modes and errors are specified in the [Web Gateway API reference](/reference/http-api/web-gateway.md). Every endpoint requires a token addressed to the gateway's peer id.

***

## What to read next

* [Build Apps: Light Node (HiggsNode)](/build-applications/java-sdk/light-node.md) - Java client for Web Gateway
* [Build Apps: HTTP / REST](/build-applications/http-rest.md) - language-agnostic integration
* [Reference: HTTP API - Web Gateway](/reference/http-api/web-gateway.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bosonnetwork.io/core-concepts/services/web-gateway.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.