How to manage diddoc’s service IDs for proxying?

[whatjakecodes]

I'm trying to figure out how to implement custom query and procedure lexicons on my app's backend.

In the readme for the oauth-client,

  // The PDS will proxy calls to the specified service in did:plc:xyz's did document.
  // These calls will be authenticated using "service auth", a single use JWT Bearer token, signed with the logged-in user's private key.
  'atproto-proxy': 'did:plc:xyz#serviceId'

Is there additional documentation for adding serviceIDs to an account’s DID document? I don’t know what proper methods there are for adding serviceIDs for my app to my personal account, or my app’s user accounts.

[yamarten]

For more information on atproto-proxy, please refer to the specifications. You can decide the serviceId as you like.

Many services use did:web for their own DID and do not use it as an atproto account. In addition to bsky.app, whtwnd.com and recipes.blue also do the same.

If you want to add service to did:plc, you will update the DID document using signPlcOperation, etc.

Goat may be helpful, but I don't know much about it.

[whatjakecodes]

That is helpful! I think I've pieced it together with your links. IIUC, I can either...

1. add the service to the app user's DID Doc, like below.

User does it manually via tool like goat. I could do it for my account manually via "Apply PLC operations" here: https://boat.kelinci.net/

Also, my app could do it via signPlcOperation like you mention.

{
  "id": "did:plc:abcd",
  "alsoKnownAs": ["at://userHandleABCD.bsky.social"],
  "verificationMethod": [],
  "service": [
    {
      "id": "#atproto_pds",
      "type": "AtprotoPersonalDataServer",
      "serviceEndpoint": "https://button.us-west.host.bsky.network"
    },
    {
      "id": "#whatJakeCodesService",
      "type": "WhatJakeCodesApiService",
      "serviceEndpoint": "https://api.whatjakecodes.com"
    }
  ]
}

or 2. more preferably host a did:web on my api server:

https://api.whatjakecodes.com/.well-known/did.json should return a JSON doc like this:

{
  "@context": [
    "https://www.w3.org/ns/did/v1"
  ],
  "id": "did:web:api.whatjakecodes.com",
  "service": [
    {
      "id": "#api",
      "type": "WhatJakeCodesApiService",
      "serviceEndpoint": "https://api.whatjakecodes.com"
    }
  ]
}

With one of these setup, I should be able to call

const response = await client.call(
  'com.whatjakecodes.customQuery',
  {
    // Params
  },
  {
    headers: {
      // for option 2:
      'atproto-proxy': 'did:web:api.whatjakecodes.com#api',
      // or for option 1:
      // 'atproto-proxy': 'did:plc:usersPersonalDID#whatJakeCodesService',
    },
  },
)

[yamarten]

Yes, you can do that. I will add a few points to note.

• If you use signPlcOperation, the update will not be reflected unless you call submitPlcOperation (or CreatePlcOp) afterwards.
• Normally, it is not expected to set service to the user's DID. The atproto-proxy header is often embedded in the client and specifies the DID that the developer knows.

[bnewbold]

Yup, the above is a good summary. In theory folks can also generate and control a PLC identity without a PDS involved at all, but there are no official or commonly-used tools to help with this at the moment (maybe something from the dev ecosystem?).

We do have it on the list to write a tutorial for using goat to do exactly this workflow. did:web also works pretty well for most service DIDs, though we don't recommend it for labelers (because labels are signed with the generating DID; there is not a good path for migrating a labeler DID, they are basically permanent).