fix: use MetaBrainz OAuth endpoint and rename musicbrainz config section to metabrainz (BB-906)

[anshikaahuja19]

Problem

The OAuth settings in the config templates pointed at an endpoint that doesn't
exist (https://musicbrainz.org/new-oauth2 returns 404), so sign-in failed on a
fresh local setup. OAuth has also moved to the metabrainz.org domain (the
/introspect endpoint used by the auth code only exists on the MetaBrainz OAuth
server, as reported on the ticket), so the config section name "musicbrainz" no
longer described what it connects to. config.local.json.example also had no
oAuthBaseURL, so the auth code built "undefined/authorize" when that file was used.

JIRA ticket: BB-906

First PR? Yes, this is my first PR to an open source project.

Solution

• oAuthBaseURL is now https://metabrainz.org/oauth2
• Renamed the "musicbrainz" config section to "metabrainz" in config.json.example,
  config.local.json.example, test.json and config.json.ctmpl
• Updated config.metabrainz references in src/server/helpers/auth.ts and
  src/server/routes/webhooks.ts, including the error message text
• Added the missing oAuthBaseURL to config.local.json.example
• In config.json.ctmpl only the JSON section was renamed. The Consul lookup paths
  (musicbrainz/...) are unchanged on purpose, since renaming them needs a matching
  change in Consul
• Also added oAuthBaseURL to test.json for consistency

Notes for existing setups: config files need the section renamed from
"musicbrainz" to "metabrainz", and developers need to register a new application
at https://metabrainz.org/profile/applications. A client registered through
musicbrainz.org fails with invalid_client.

• I have run the code and manually tested the changes: rebuilt the Docker
  image and completed a full sign-in locally with a newly registered application.

AI usage

• I did not use any AI
• I have used AI in this PR (add more details below)

If you did use AI:

• I used AI tools for communication
• I used AI tools for coding
• I understand all the changes made in this PR

I used Claude to help debug my local setup, suggest the sed commands for the
rename, and draft the ticket and PR text. I reviewed each diff, ran the changes,
and tested sign-in myself.

Action

The dev-docs installation page (bookbrainz-dev-docs) will be updated in a
separate PR.

[dheeraj-juvvadi]

Confirmed the endpoint issue during local setup: /new-oauth2/authorize returns 404, while /oauth2/authorize returns 200. Current master still has the old URL in config/config.json.example. This supports the template correction; I have not verified a complete OAuth sign-in. Verification and this comment were prepared with Codex.

[MonkeyDo]

Thanks for looking into this!
More comments below, let's take the opportunity to clean up other parts of the codebase and docs to follow the same changes.

[MonkeyDo]

Since we are here, and with the context of my other comment, we probably want to rename this to "metabrainz", and modify all the places in the code that access this property.

[dheeraj-juvvadi]

The latest commit has the MetaBrainz endpoint. I checked the remaining rename at fd43d06; it covers six files:

• config/config.json.example
• config/config.local.json.example
• config/test.json
• config/config.json.ctmpl
• src/server/helpers/auth.ts
• src/server/routes/webhooks.ts (including the config path in the error message)

One related fix: add "oAuthBaseURL": "https://metabrainz.org/oauth2" to the local config template too. I loaded it through the config helper with --config; the field is missing, so the auth code builds undefined/authorize. The loader reads that file on its own and does not merge the default template.

For config.json.ctmpl, the JSON section name and the Consul lookup paths are separate. The section can become metabrainz while the existing musicbrainz/... lookup paths stay in place. Renaming those paths also needs a matching change in Consul. Existing config files need the section renamed when the code is deployed.

In the developer docs, the current application page is MetaBrainz Applications, as listed in the OAuth registration docs. The installation page needs updates in Configuration, Local Configuration, and the account setup step under Search server setup. Keep the callback at http://localhost:9099/cb for the default port.

The PR description should also use the MetaBrainz URL and mention the config rename. These checks cover config loading and references; I have not tested a complete sign-in.

[anshikaahuja19]

Thanks for the detailed review and for listing the exact files! Done so far (pushed to this PR): - Applied the suggested https://metabrainz.org/oauth2 endpoint in config.json.example - Renamed the musicbrainz section to metabrainz in all six files: config.json.example, config.local.json.example, test.json, config.json.ctmpl, auth.ts and webhooks.ts (including the error message text) - Added the missing oAuthBaseURL to config.local.json.example - In config.json.ctmpl I renamed only the JSON section and left the Consul lookup paths as musicbrainz/..., as you suggested - I also added oAuthBaseURL to test.json for consistency. Happy to drop that if you'd rather keep it to the files you listed - Tested a complete sign-in locally after rebuilding the Docker image and registering a new application at metabrainz.org/profile/applications. It works. Note that my old client registered via musicbrainz.org failed with invalid_client, so existing developers will need to re-register their apps Still to do: - Update the PR description to use the MetaBrainz URL and mention the config rename - A final sweep for any remaining references to config.musicbrainz outside these files - Dev docs: a separate PR to bookbrainz-dev-docs updating the installation page (Configuration, Local Configuration, and the account setup step under Search server setup) to point to metabrainz.org/profile/applications, keeping the callback at http://localhost:9099/cb Let me know if you'd prefer the docs changes handled differently.

…

On Tue, Oct 6, 2026 at 9:35 AM Dheeraj ***@***.***> wrote: *dheeraj-juvvadi* left a comment (metabrainz/bookbrainz-site#1373) <#1373 (comment)> The latest commit has the MetaBrainz endpoint. I checked the remaining rename at fd43d06; it covers six files: - config/config.json.example - config/config.local.json.example - config/test.json - config/config.json.ctmpl - src/server/helpers/auth.ts - src/server/routes/webhooks.ts (including the config path in the error message) One related fix: add "oAuthBaseURL": "https://metabrainz.org/oauth2" to the local config template too. I loaded it through the config helper with --config; the field is missing, so the auth code builds undefined/authorize. The loader reads that file on its own and does not merge the default template. For config.json.ctmpl, the JSON section name and the Consul lookup paths are separate. The section can become metabrainz while the existing musicbrainz/... lookup paths stay in place. Renaming those paths also needs a matching change in Consul. Existing config files need the section renamed when the code is deployed. In the developer docs, the current application page is MetaBrainz Applications <https://metabrainz.org/profile/applications>, as listed in the OAuth registration docs <https://github.com/metabrainz/metabrainz.org/blob/master/docs/oauth/registration.rst>. The installation page needs updates in Configuration, Local Configuration, and the account setup step under Search server setup. Keep the callback at http://localhost:9099/cb for the default port. The PR description should also use the MetaBrainz URL and mention the config rename. These checks cover config loading and references; I have not tested a complete sign-in. — Reply to this email directly, view it on GitHub <#1373?email_source=notifications&email_token=BV2CEC5GFNSTIPKDJTQALAL5SRVQDA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMMBQHEYTAMJRGM22M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-6009101135>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BV2CEC4A4JUBGHUZDSKPWFT5SRVQDAVCNFSNUABEKJSXA33TNF2G64TZHMZDQNJSGE4DSNR3JFZXG5LFHM2TKNBUGMYTMNRSGSQXMAQ> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BV2CECYBWUP3FVNPHGUPIST5SRVQDA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMMBQHEYTAMJRGM22M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/BV2CEC47NTHNYSGK3L5FTM35SRVQDA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMMBQHEYTAMJRGM22M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>