WeChat Login Setup

This page is specifically about the "WeChat Open Platform -> Website App -> WeChat Login" flow.

It is not Official Account login, and it is not Mini Program login.

The primary shape of this flow is PC-side QR-code login.

However, according to the current WeChat documentation, newer Windows and Mac WeChat desktop clients may sometimes show a fast-login confirmation instead of requiring a QR scan every time when the user is already signed in locally.

What you need first

Before integration, make sure you already have:

• a WeChat Open Platform developer account
• a Website App that has passed review
• WeChat Login enabled and approved for that Website App
• the AppID and AppSecret for that Website App

If these prerequisites are missing, adding a wechat provider in code will not make real login work.

What to configure in Downcity

The accounts service reads these two environment variables:

• WECHAT_CLIENT_ID
• WECHAT_CLIENT_SECRET

That means:

• WeChat Website App AppID -> WECHAT_CLIENT_ID
• WeChat Website App AppSecret -> WECHAT_CLIENT_SECRET

in Federation env.

Which callback URL to register

The OAuth callback URL used by the accounts service is fixed:

https://your-base-domain/v1/accounts/oauth/callback

For example:

https://downcity.example.com/v1/accounts/oauth/callback

The callback URL registered in the WeChat Open Platform Website App console must match this exact URL.

If you use a custom domain, register the same path under that custom domain.

Why the domain often fails

When WeChat website login starts, the accounts service generates a login URL under:

https://open.weixin.qq.com/connect/qrconnect

with the current City redirect_uri.

If the callback domain configured in WeChat does not match the real public City domain used by the downcity, login usually fails immediately.

So two things must stay aligned:

• the real public City domain used by the downcity
• the exact callback URL registered in WeChat

How the frontend should use it

Do not hardcode the WeChat login button. Ask the server which providers are actually enabled:

const providers = await guest.service("accounts").get("providers");

If the response contains:

{ id: "wechat", type: "oauth", enabled: true }

then render a WeChat login entry.

To start login:

const start = await guest.service("accounts").action("oauth/start").invoke({
  provider: "wechat",
  city_id: "city_demo",
});

Then send the user to start.url, and use oauth/result to poll or confirm the result:

const result = await guest.service("accounts").get("oauth/result", {
  state: start.state,
});

What this flow returns

After WeChat login succeeds, the accounts service still returns a normal City user_token.

So the downcity does not need a special post-login client flow just because the user came from WeChat:

const user = new City({
  role: "user",
  city_url: "https://base.example.com",
  city_id: "city_demo",
  user_token: result.user_token,
});

Common mistakes

• mixing Website App login with Official Account login
• mixing Website App login with Mini Program login
• configuring one domain in WeChat while the downcity actually uses another City domain
• hardcoding the wechat button instead of checking providers first

Related docs

• For the overall OAuth flow, continue with OAuth and Session
• For the full integration path, read Accounts Service
• After deployment, write WECHAT_CLIENT_ID and WECHAT_CLIENT_SECRET into Federation env through the Admin API or the fed admin workspace