# Voidnet (/docs/learn/voidnet)



The Voidnet is the central routing layer of the Voidnet Console platform. You send it a request; it authenticates you, enforces your subscription and usage limits, and proxies the request to the publisher's server. You never connect to a publisher directly.

```
Buyer (API key or JWT)  →  Voidnet  →  Publisher's server
```

## What the gateway does [#what-the-gateway-does]

1. **Authenticates** your credential (API key or JWT).
2. **Checks your purchase** of the app and your tier's meter.
3. **Enforces rate limits** (per-minute, per-day, monthly meter).
4. **Routes** the request to the publisher's server.
5. **Returns** the publisher's response, or a gateway error if something fails.

You do not need to know the publisher's server URL. The gateway resolves it from the `username/appname` in your request path — see [Identity](https://docs.openvoidnet.com/docs/learn/identity) for the naming rules behind the pair.

## Endpoint [#endpoint]

All app requests go through one endpoint. The adapter in the path selects the protocol:

```
POST /v1-beta/{adapter}/{username}/{appname}
```

| Parameter              | Value                                                                             |
| ---------------------- | --------------------------------------------------------------------------------- |
| `adapter`              | `mcp` or `llm` — see [Void Apps](https://docs.openvoidnet.com/docs/learn/void-apps)                           |
| `username`             | Publisher's public username                                                       |
| `appname`              | App name, unique per publisher                                                    |
| `Authorization`        | `Bearer <vnb-sk-...>`, or `Bearer <JWT>` (scope `mcp:tools` or `llm:completions`) |
| `MCP-Protocol-Version` | `2026-07-28` (required for `mcp` only)                                            |
| `Mcp-Method`           | JSON-RPC method name (required for `mcp` only)                                    |
| `Mcp-Name`             | Tool/resource/prompt name (required for `mcp` only)                               |

**MCP — Stateless 2026-07-28:**

* Only `POST` is supported. `GET` and `DELETE` return `405 Method Not Allowed`.
* SSE streams are per-request on POST; close = cancel. No `Last-Event-ID`, no `Mcp-Session-Id`.

**LLM — OpenAI compatible:**

```
POST /v1-beta/llm/{username}/{appname}
Authorization: Bearer vnb-sk-...
Content-Type: application/json

Body: {"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"hi"}],"stream":false}
```

* One model per app — the `model` you send must match the app's published model exactly.
* `stream:true` is supported (SSE); the gateway injects `stream_options.include_usage:true` when missing, and streams without a final usage chunk fail loudly instead of going unbilled. Multimodal inputs (`image_url`, `audio`) are rejected — TEXT only.
* Your LLM server must expose `POST {serverUrl}/chat/completions` (`{serverUrl}` is your configured Server URL, which already ends in `/v1`) and accept any `Authorization: Bearer <token>` header.

Plus operational endpoints:

| Method | Path                                      | Purpose                                                                            |
| ------ | ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET`  | `/health`                                 | Health check (db + redis)                                                          |
| `POST` | `/oauth/token`                            | Issue JWT access tokens (client\_credentials, authorization\_code, refresh\_token) |
| `GET`  | `/.well-known/oauth-authorization-server` | OAuth metadata (RFC 8414)                                                          |
| `GET`  | `/.well-known/oauth-protected-resource`   | OAuth metadata (RFC 9728)                                                          |
| `GET`  | `/.well-known/jwks.json`                  | Public signing keys                                                                |
| `GET`  | `/authorize`                              | OAuth 2.1 authorization code + PKCE, login and consent pages (interactive clients) |
| `POST` | `/authorize`                              | Submit login + consent, issue authorization code (interactive clients)             |

For the full request/response schema of every operation, see the [API Reference](https://docs.openvoidnet.com/docs/reference/api-reference) — it is generated from the gateway source and cannot drift.

## Authentication [#authentication]

Two credential types, both in the `Authorization: Bearer` header. The gateway auto-detects which you're using:

* **API keys** (`vnb-sk-*`) — long-lived, generated in the Console.
* **JWT access tokens** — short-lived (1 hour), obtained from `POST /oauth/token`. Use these in production.

A 3-segment (dot-separated) value is treated as a JWT; a `vnb-sk-` prefix is treated as an API key.

## Errors [#errors]

All gateway errors use one shape (OAuth endpoints are the exception — see [Error Reference](https://docs.openvoidnet.com/docs/reference/error-reference#error-reference)):

```json
{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "status": 429
  }
}
```