Service entries

Manage the service entries published in the instance’s DID document. Each entry declares an atproto service type (e.g. AtprotoLabeler, BskyFeedGenerator). Its access mode decides which XRPC methods a caller using service auth addressed to that entry may call. 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"

List service entries

GET /admin/service-entries

TypeScript

interface ServiceEntry {
  id: number;
  fragment_id: string;
  service_type: string;
  access_mode: "all" | "specific";
  created_at: string;
  updated_at: string;
}

const response = await fetch("http://127.0.0.1:3000/admin/service-entries", {
  headers,
});
const data: ServiceEntry[] = await response.json();

JavaScript

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

Rust

let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:3000/admin/service-entries")
    .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/service-entries", 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/service-entries -H "$AUTH"

Response: 200 OK

[
  {
    "id": 1,
    "fragment_id": "#happyview",
    "service_type": "AtprotoLabeler",
    "access_mode": "all",
    "created_at": "2026-05-09T12:00:00.000000+00:00",
    "updated_at": "2026-05-09T12:00:00.000000+00:00"
  }
]

Create a service entry

POST /admin/service-entries

TypeScript

const response = await fetch("http://127.0.0.1:3000/admin/service-entries", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fragment_id: "#feed",
    service_type: "BskyFeedGenerator",
  }),
});
const data: ServiceEntry = await response.json();

JavaScript

const response = await fetch("http://127.0.0.1:3000/admin/service-entries", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fragment_id: "#feed",
    service_type: "BskyFeedGenerator",
  }),
});
const data = await response.json();

Rust

let response = client
    .post("http://127.0.0.1:3000/admin/service-entries")
    .bearer_auth(token)
    .json(&serde_json::json!({
        "fragment_id": "#feed",
        "service_type": "BskyFeedGenerator"
    }))
    .send()
    .await?;
let data: serde_json::Value = response.json().await?;

Go

body := bytes.NewBufferString(`{"fragment_id": "#feed", "service_type": "BskyFeedGenerator"}`)
req, _ := http.NewRequest("POST", "http://127.0.0.1:3000/admin/service-entries", 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 POST http://127.0.0.1:3000/admin/service-entries \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{ "fragment_id": "#feed", "service_type": "BskyFeedGenerator" }'

Field	Type	Required	Description
fragment_id	string	yes	DID document fragment (e.g. #feed, #happyview). Must be unique
service_type	string	yes	atproto service type (e.g. BskyFeedGenerator)

The entry is created with access_mode set to all. The endpoint URL is derived from PUBLIC_URL. A duplicate fragment_id returns 409 Conflict.

Response: 201 Created, with the created entry

{
  "id": 2,
  "fragment_id": "#feed",
  "service_type": "BskyFeedGenerator",
  "access_mode": "all",
  "created_at": "2026-05-09T12:00:00.000000+00:00",
  "updated_at": "2026-05-09T12:00:00.000000+00:00"
}

Update a service entry

PUT /admin/service-entries/{id}

TypeScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1", {
  method: "PUT",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    service_type: "AtprotoLabeler",
    access_mode: "specific",
  }),
});

JavaScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1", {
  method: "PUT",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    service_type: "AtprotoLabeler",
    access_mode: "specific",
  }),
});

Rust

client
    .put("http://127.0.0.1:3000/admin/service-entries/1")
    .bearer_auth(token)
    .json(&serde_json::json!({
        "service_type": "AtprotoLabeler",
        "access_mode": "specific"
    }))
    .send()
    .await?;

Go

body := bytes.NewBufferString(`{"service_type": "AtprotoLabeler", "access_mode": "specific"}`)
req, _ := http.NewRequest("PUT", "http://127.0.0.1:3000/admin/service-entries/1", 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/service-entries/1 \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "AtprotoLabeler", "access_mode": "specific" }'

Field	Type	Required	Description
fragment_id	string	no	Updated DID document fragment
service_type	string	no	Updated service type
access_mode	string	no	all, or specific (only the XRPCs bound to this entry). Any other value is 400 Bad Request

All fields are optional. Only provided fields are updated. Returns 404 Not Found if the entry doesn’t exist.

Response: 204 No Content

Delete a service entry

DELETE /admin/service-entries/{id}

TypeScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1", {
  method: "DELETE",
  headers,
});

JavaScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1", {
  method: "DELETE",
  headers,
});

Rust

client
    .delete("http://127.0.0.1:3000/admin/service-entries/1")
    .bearer_auth(token)
    .send()
    .await?;

Go

req, _ := http.NewRequest("DELETE", "http://127.0.0.1:3000/admin/service-entries/1", 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 -X DELETE http://127.0.0.1:3000/admin/service-entries/1 \
  -H "$AUTH"

Returns 404 Not Found if the entry doesn’t exist.

Response: 204 No Content

List XRPCs for a service entry

GET /admin/service-entries/{id}/xrpcs

Returns the lexicon IDs (NSIDs) bound to this service entry.

TypeScript

const response = await fetch("http://127.0.0.1:3000/admin/service-entries/1/xrpcs", {
  headers,
});
const data: string[] = await response.json();

JavaScript

const response = await fetch("http://127.0.0.1:3000/admin/service-entries/1/xrpcs", {
  headers,
});
const data = await response.json();

Rust

let response = client
    .get("http://127.0.0.1:3000/admin/service-entries/1/xrpcs")
    .bearer_auth(token)
    .send()
    .await?;
let data: Vec<String> = response.json().await?;

Go

req, _ := http.NewRequest("GET", "http://127.0.0.1:3000/admin/service-entries/1/xrpcs", 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/service-entries/1/xrpcs -H "$AUTH"

Response: 200 OK

["app.bsky.feed.getFeedSkeleton", "app.bsky.feed.describeFeedGenerator"]

Add XRPCs to a service entry

POST /admin/service-entries/{id}/xrpcs

TypeScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1/xrpcs", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lexicon_ids: ["app.bsky.feed.getFeedSkeleton"],
  }),
});

JavaScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1/xrpcs", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lexicon_ids: ["app.bsky.feed.getFeedSkeleton"],
  }),
});

Rust

client
    .post("http://127.0.0.1:3000/admin/service-entries/1/xrpcs")
    .bearer_auth(token)
    .json(&serde_json::json!({
        "lexicon_ids": ["app.bsky.feed.getFeedSkeleton"]
    }))
    .send()
    .await?;

Go

body := bytes.NewBufferString(`{"lexicon_ids": ["app.bsky.feed.getFeedSkeleton"]}`)
req, _ := http.NewRequest("POST", "http://127.0.0.1:3000/admin/service-entries/1/xrpcs", 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 POST http://127.0.0.1:3000/admin/service-entries/1/xrpcs \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{ "lexicon_ids": ["app.bsky.feed.getFeedSkeleton"] }'

Field	Type	Required	Description
lexicon_ids	string[]	yes	Lexicon NSIDs to bind to this entry

Response: 204 No Content

Remove XRPCs from a service entry

DELETE /admin/service-entries/{id}/xrpcs

TypeScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1/xrpcs", {
  method: "DELETE",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lexicon_ids: ["app.bsky.feed.getFeedSkeleton"],
  }),
});

JavaScript

await fetch("http://127.0.0.1:3000/admin/service-entries/1/xrpcs", {
  method: "DELETE",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lexicon_ids: ["app.bsky.feed.getFeedSkeleton"],
  }),
});

Rust

client
    .delete("http://127.0.0.1:3000/admin/service-entries/1/xrpcs")
    .bearer_auth(token)
    .json(&serde_json::json!({
        "lexicon_ids": ["app.bsky.feed.getFeedSkeleton"]
    }))
    .send()
    .await?;

Go

body := bytes.NewBufferString(`{"lexicon_ids": ["app.bsky.feed.getFeedSkeleton"]}`)
req, _ := http.NewRequest("DELETE", "http://127.0.0.1:3000/admin/service-entries/1/xrpcs", 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 DELETE http://127.0.0.1:3000/admin/service-entries/1/xrpcs \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{ "lexicon_ids": ["app.bsky.feed.getFeedSkeleton"] }'

Field	Type	Required	Description
lexicon_ids	string[]	yes	Lexicon NSIDs to unbind from this entry

Response: 204 No Content

List services for a lexicon

GET /admin/lexicons/{id}/services

Returns service entries that grant access to the specified lexicon.

TypeScript

const response = await fetch("http://127.0.0.1:3000/admin/lexicons/app.bsky.feed.getFeedSkeleton/services", {
  headers,
});
const data: ServiceEntry[] = await response.json();

JavaScript

const response = await fetch("http://127.0.0.1:3000/admin/lexicons/app.bsky.feed.getFeedSkeleton/services", {
  headers,
});
const data = await response.json();

Rust

let response = client
    .get("http://127.0.0.1:3000/admin/lexicons/app.bsky.feed.getFeedSkeleton/services")
    .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/lexicons/app.bsky.feed.getFeedSkeleton/services", 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/lexicons/app.bsky.feed.getFeedSkeleton/services -H "$AUTH"

Response: 200 OK with an array of ServiceEntry objects.

Sync to PLC directory

These endpoints publish your service entries to the PLC directory so they appear in the DID document. The sync method depends on the service identity mode.

Direct sync (did:plc mode)

POST /admin/service-entries/sync-plc

Signs and submits a PLC update operation using the stored rotation key. Only available when the identity mode is did_plc.

TypeScript

await fetch("http://127.0.0.1:3000/admin/service-entries/sync-plc", {
  method: "POST",
  headers,
});

JavaScript

await fetch("http://127.0.0.1:3000/admin/service-entries/sync-plc", {
  method: "POST",
  headers,
});

Rust

let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:3000/admin/service-entries/sync-plc")
    .bearer_auth(token)
    .send()
    .await?;

Go

req, _ := http.NewRequest("POST", "http://127.0.0.1:3000/admin/service-entries/sync-plc", 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 -X POST http://127.0.0.1:3000/admin/service-entries/sync-plc -H "$AUTH"

The operation keeps the DID’s existing rotation keys, handles and services, and adds the instance’s verification methods. Each service entry is written with PUBLIC_URL as its endpoint, and a service pointing at PUBLIC_URL that no longer has an entry is removed.

Returns 400 Bad Request if no identity is configured, the identity mode is not did_plc, or no DID is registered yet. Returns 500 Internal Server Error if TOKEN_ENCRYPTION_KEY is not set.

Response: 204 No Content

Request PLC token (attach_account mode)

POST /admin/service-entries/sync-plc/request

Requests a PLC operation signature token via the attached account’s PDS. This sends an email confirmation code to the account holder. Only available when the identity mode is attach_account.

TypeScript

await fetch("http://127.0.0.1:3000/admin/service-entries/sync-plc/request", {
  method: "POST",
  headers,
});

JavaScript

await fetch("http://127.0.0.1:3000/admin/service-entries/sync-plc/request", {
  method: "POST",
  headers,
});

Rust

let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:3000/admin/service-entries/sync-plc/request")
    .bearer_auth(token)
    .send()
    .await?;

Go

req, _ := http.NewRequest("POST", "http://127.0.0.1:3000/admin/service-entries/sync-plc/request", 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 -X POST http://127.0.0.1:3000/admin/service-entries/sync-plc/request -H "$AUTH"

Returns 400 Bad Request if the identity mode is not attach_account, no identity is configured, or no attached account is set. Returns 401 Unauthorized when the attached account’s PDS session has expired; re-authenticate on the Service Identity page.

Response: 204 No Content

Submit PLC token (attach_account mode)

POST /admin/service-entries/sync-plc/submit

Builds the same changes as a direct sync, has the attached account’s PDS sign them with the email confirmation code, and submits the signed operation through that PDS.

TypeScript

await fetch("http://127.0.0.1:3000/admin/service-entries/sync-plc/submit", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    token: "123456"
  }),
});

JavaScript

await fetch("http://127.0.0.1:3000/admin/service-entries/sync-plc/submit", {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    token: "123456"
  }),
});

Rust

let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:3000/admin/service-entries/sync-plc/submit")
    .bearer_auth(token)
    .json(&serde_json::json!({
        "token": "123456"
    }))
    .send()
    .await?;

Go

body := bytes.NewBufferString(`{
  "token": "123456"
}`)
req, _ := http.NewRequest("POST", "http://127.0.0.1:3000/admin/service-entries/sync-plc/submit", 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 POST http://127.0.0.1:3000/admin/service-entries/sync-plc/submit \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{ "token": "123456" }'

Field	Type	Required	Description
token	string	yes	Email confirmation code from the PDS

Returns 400 Bad Request if the identity mode is not attach_account, no identity is configured, or no attached account is set. Returns 401 Unauthorized when the attached account’s PDS session has expired; re-authenticate on the Service Identity page.

Response: 204 No Content