XRPC proxy

Control which unrecognized XRPC methods HappyView forwards, and where they go. Lexicons registered on the instance are always served, whatever this setting says.

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

const 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)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

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)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

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 routing looks up where a lexicon is defined. For com.atproto.repo.* that’s the account publishing those lexicons, and the request carries no credentials, so a write to the caller’s repo works only 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	A new NSID pattern is not a valid NSID, or a wildcard pattern has fewer than two segments before .*, an empty segment, or a character other than letters, digits and hyphens. Patterns already stored are not checked again
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"
}