Get Started

Get credentials and call a published Void App through the Voidnet. Every request uses the same pattern regardless of the app.

Prerequisites

A Voidnet Console account (sign up)
An HTTP client (curl, Postman, or any language)

Step 1: Get credentials

You need a bearer credential to authenticate requests. Two options:

Option A: API key (simplest)

In the Console, open API Keys → Generate Key. You get a key like:

vnb-sk-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6

Save it now — it is shown only once. Lost keys must be revoked and regenerated.

Prefix	Type	Use case
`vnb-sk-`	Buyer service key	General purpose
`vai-sk-`	Ambient key	Automated / integrated workflows

Option B: OAuth access token (production)

Exchange an API key for a short-lived JWT. Better for production because tokens expire and can be scoped.

curl -X POST http://localhost:8080/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=vnb-sk-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp:tools"
}

The access_token is a JWT valid for 1 hour. Use it as a Bearer credential anywhere you would use an API key. When it expires the gateway returns 401 api_key_expired — request a new token and retry.

The scope defaults to mcp:tools. A token with an mcp: prefix scope can call any MCP method. Empty scope (legacy keys) is unrestricted.

Step 2: Find an app

Browse the Marketplace. Note two things about the app you want:

Publisher username — the developer's public identifier (e.g. acmecorp)
App name — unique per publisher (e.g. weather-tools)

Purchase the app (free tiers require clicking "Get" to create the purchase record).

Just want to call a tool?

You do not need sessions or SSE to call a tool. Skip to Step 3.

Step 3: Send your first request

The URL encodes the protocol, publisher, and app:

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

For MCP tools the adapter is mcp. Example using the test app:

curl -X POST http://localhost:8080/v1-beta/mcp/acmecorp/weather-tools \
  -H "Authorization: Bearer vnb-sk-a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

Response (the exact tools depend on the publisher):

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "get_forecast",
        "description": "Get weather forecast for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City name or coordinates" },
            "days": { "type": "integer", "description": "Number of days (1-7)" }
          },
          "required": ["location"]
        }
      }
    ]
  }
}

Step 4: Call a tool

Use tools/call with the tool name and arguments:

curl -X POST http://localhost:8080/v1-beta/mcp/acmecorp/weather-tools \
  -H "Authorization: Bearer vnb-sk-a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "get_forecast",
      "arguments": { "location": "London", "days": 3 }
    }
  }'

Next steps

Buyer Guide (MCP) — OAuth, sessions, SSE, and advanced patterns
API Reference — complete, generated from the gateway source
Error Reference — full error code catalog

Get Started

On this page