MCP OAuth

The Voidnet acts as an OAuth 2.0 authorization server, issuing JWT access tokens for production systems.

Token types

JWT access tokens

Access tokens are JSON Web Tokens (JWTs) signed with RS256. They are three base64url-encoded segments separated by dots:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature

Each token contains:

• sub — Buyer UUID
• scope — Permission scope (e.g. mcp:tools)
• exp — Expiration time (default 1 hour)
• iat — Issued at time
• iss — Voidnet issuer URL
• aud — Voidnet issuer URL (fixed at mint time; no client-controlled audience input)
• kid — Key ID identifying the signing key in the JWKS

API keys

The Voidnet also accepts API keys (vnb-sk-*, vai-sk-*) as a simpler alternative. See the Buyer Guide for API key management.

Grant types

client_credentials

Exchange your API key for a short-lived JWT:

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"

Successful response:

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

The returned access_token is a JWT usable in any Authorization: Bearer header.

Notes:

• No separate client_secret is needed — the API key itself is the secret
• An optional scope parameter may be provided (defaults to mcp:tools)
• The aud claim is always the Voidnet issuer URL — the token endpoint accepts no client-controlled audience input

Using tokens

All requests to the Voidnet use the Authorization: Bearer header:

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

# JWT access token
TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -X POST http://localhost:8080/v1-beta/mcp/acmecorp/weather-tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list"}'

The Voidnet auto-detects the credential type — three dot-separated segments means JWT, otherwise API key.

Token expiration

Tokens have an exp claim. When a token expires, the Voidnet returns api_key_expired (401):

1. Detect the 401 response
2. Request a new token from POST /oauth/token
3. Retry the request with the new token

Publisher authentication

When the Voidnet proxies a request to a publisher's server, it authenticates using the publisher's API key (vnp-sk-*):

Authorization: Bearer vnp-sk-27fc6268dc64a9ba2c4cb92489e9175cbf404e260beb268b976f1a56582eff3

Publisher keys are:

• Generated in the Console when publishing an app
• The Voidnet always sends vnp-sk-* regardless of how the buyer authenticated
• Sent to the publisher server on every proxied request

Endpoints

OAuth endpoints

The Voidnet acts as an OAuth 2.0 authorization server:

Credential management

API keys are managed through the Voidnet:

• Generate — Create a new key from the API Keys section
• Revoke — Immediately invalidate a compromised key
• Rotate — Generate a new key, update your configuration, revoke the old one

OAuth access tokens are obtained programmatically:

• client_credentials — Exchange an API key for a JWT at POST /oauth/token
• Tokens expire after a configurable period (default 1 hour)

Credential security best practices

• Store API keys and tokens in environment variables, not in code
• Use a secrets manager in production
• Rotate API keys periodically
• Revoke compromised keys immediately
• Never expose credentials in client-side code, logs, or version control
• Use short-lived JWT access tokens in production systems instead of raw API keys