XRPC proxy

Control which unrecognized XRPC methods HappyView forwards, and where they go. Locally registered lexicons are always served regardless of this setting.

All endpoints require the settings:manage permission.

TypeScript

const TOKEN = "hv_..."; // your API key
const headers = { Authorization: `Bearer ${TOKEN}` };

JavaScript

const TOKEN = "hv_..."; // your API key
const headers = { Authorization: `Bearer ${TOKEN}` };

Rust

let token = "hv_..."; // your API key

Go

token := "hv_..." // your API key

cURL

# All examples assume $TOKEN is an API key (hv_...)
AUTH="Authorization: Bearer $TOKEN"

Get proxy config

GET /admin/settings/xrpc-proxy

TypeScript

interface XrpcProxyConfig {
  mode: string;
  nsids: string[];
  routing: "authority" | "serviceproxy";
}

const response = await fetch("http://127.0.0.1:3000/admin/settings/xrpc-proxy", {
  headers,
});
const data: XrpcProxyConfig = await response.json();

JavaScript

const response = await fetch("http://127.0.0.1:3000/admin/settings/xrpc-proxy", {
  headers,
});
const data = await response.json();

Rust

let response = client
    .get("http://127.0.0.1:3000/admin/settings/xrpc-proxy")
    .bearer_auth(token)
    .send()
    .await?;
let data: serde_json::Value = response.json().await?;

Go

req, _ := http.NewRequest("GET", "http://127.0.0.1:3000/admin/settings/xrpc-proxy", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)

cURL

curl http://127.0.0.1:3000/admin/settings/xrpc-proxy -H "$AUTH"

Response: 200 OK

{
  "mode": "allowlist",
  "nsids": ["com.example.feed.*", "games.gamesgamesgamesgames.*"],
  "routing": "authority"
}

Returns {"mode": "open", "nsids": [], "routing": "authority"} when no config has been saved.

Update proxy config

PUT /admin/settings/xrpc-proxy

TypeScript

const response = await fetch("http://127.0.0.1:3000/admin/settings/xrpc-proxy", {
  method: "PUT",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "allowlist",
    nsids: ["com.example.feed.*"],
  }),
});

JavaScript

const response = await fetch("http://127.0.0.1:3000/admin/settings/xrpc-proxy", {
  method: "PUT",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "allowlist",
    nsids: ["com.example.feed.*"],
  }),
});

Rust

let response = client
    .put("http://127.0.0.1:3000/admin/settings/xrpc-proxy")
    .bearer_auth(token)
    .json(&serde_json::json!({
        "mode": "allowlist",
        "nsids": ["com.example.feed.*"]
    }))
    .send()
    .await?;

Go

body := bytes.NewBufferString(`{
  "mode": "allowlist",
  "nsids": ["com.example.feed.*"]
}`)
req, _ := http.NewRequest("PUT", "http://127.0.0.1:3000/admin/settings/xrpc-proxy", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

cURL

curl -X PUT http://127.0.0.1:3000/admin/settings/xrpc-proxy \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "allowlist",
    "nsids": ["com.example.feed.*"]
  }'

Response: 204 No Content

Field	Type	Required	Description
mode	string	yes	Whether a method may be proxied
nsids	string[]	no	Patterns for allowlist and blocklist
routing	string	no	Where a proxied method goes. Left out, the stored routing is unchanged

Changes take effect immediately, with no restart.

Modes

Mode	Behavior
disabled	Block all proxy requests. Return 403 for every unrecognized NSID.
open	Proxy everything (default).
allowlist	Proxy only NSIDs matching a pattern in nsids. Return 403 for the rest.
blocklist	Proxy everything except NSIDs matching a pattern in nsids.

When mode is disabled or open, any nsids in the request body are ignored and stored as [].

Routing

Routing	Behavior
authority	Forward to the authority the NSID’s _lexicon DNS record names, with no credentials (default).
serviceproxy	Forward to the caller’s own PDS, authenticated as the caller, per service proxying. An atproto-proxy header is passed through, and the PDS relays the request onwards. An anonymous query is 401 Unauthorized, because the destination depends on who is asking.

authority answers where a schema is defined, not who serves a request. For com.atproto.repo.* that’s the account publishing those lexicons, so an authenticated write only works under serviceproxy.

NSID patterns

Patterns are dotted NSID identifiers. Trailing wildcards are supported:

• com.example.feed.getHot: exact match
• com.example.feed.*: matches any NSID starting with com.example.feed.
• games.gamesgamesgamesgames.*: matches the entire namespace

Mid-segment wildcards (e.g., com.*.feed) are not supported.

Validation errors

Status	Cause
400	An NSID pattern is empty, has fewer than two segments, contains invalid characters, or uses an unsupported wildcard
422	mode is not one of disabled, open, allowlist, blocklist, or routing is not authority or serviceproxy

Blocked request response

When the proxy denies a request, the client receives:

403 Forbidden

{
  "error": "NSID not allowed by proxy policy"
}