WeChat Open Platform
Website SDK Documentation

WeChat Login for Web Apps

Content

  1. Getting Started
  2. Authorization Process
  3. Step 1: Getting the code parameter
    • Example flow
    • Customizing Your Login Page
  4. Step 2: Passing the code to get the access_token
  5. Renewing Your Token
  6. Step 3: Using APIs with the access_token
  7. FAQs

Getting Started

This feature lets users log into third-party sites on their computer by scanning a QR code displayed on the page, using their mobile phone. This reduces any friction new users may encounter in using your site, saving the time and hassle of having to remember yet another password.

WeChat Login for Web Apps is based on the OAuth 2.0 protocol. To use it, you must register a developer account via our management interface.

Once registered, you should get an AppID and AppSecret for your app by submitting your app on the portal. After your application has been approved, you can start using this API!

Authorization Process

The process works like this:

  1. The third party redirects the user to a page hosted by WeChat containing a QR code. After the user permits the third party site to access their account, WeChat will redirect the user back to the site, passing along a temporary code parameter in the query string.

  2. Using this code parameter, along with the previously-obtained AppID and AppSecret, the third-party app can receive an access_token.

  3. Finally, the third party app can use this access_token to call other APIs, such as the one for retrieving the user's profile info.

Step 1: Getting the code parameter

When a user selects the “Login with WeChat” option, the third-party site should link the user to a URL following the format below. This page will display a QR code that the user can scan.

https://open.weixin.qq.com/connect/qrconnect?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect

If an error appears after loading this URL, double-check the parameters passed. The domain in the redirect_ui must match what was entered and approved for your app on our developer portal. Also, be sure to use the scope "snsapi_login".

Parameters
Parameter Required Explanation
appid Yes The ID registered for your application.
redirect_uri Yes The URL the user will be redirected to after authorization. Must be urlencoded.
response_type Yes Use 'code'
scope Yes Comma-delimited list of scopes authorized by user. For web login, use 'snsapi_login'
state No This can be any state information you wish to preserve across the OAuth process, for example a token to prevent CSRF attacks.
Response

If the user authorizes the login, the parameters passed will include both code and state information:

redirect_uri?code=CODE&state=STATE

If the user refuses to authorize the login, the parameters passed in the query string will only include state:

redirect_uri?state=STATE
Example Flow

The commerce website YiHaoDian uses this API to allow users to login using a WeChat account. First, the user opens this page on their site:

https://passport.yhd.com/wechat/login.do

Afterwards, the site redirects the user to something like:

https://open.weixin.qq.com/connect/qrconnect?appid=wxbdc5610cc59c1631&redirect_uri=https%3A%2F%2Fpassport.yhd.com%2Fwechat%2Fcallback.do&response_type=code&scope=snsapi_login&state=3d6be0a4035d839573b04816624a415e#wechat_redirect

Then, once the user scans the code on their phone and authorizes the login, we redirect them back to YiHaoDian, passing along the appropriate parameters:

https://passport.yhd.com/wechat/callback.do?code=CODE&state=3d6be0a4035d839573b04816624a415e

Customizing Your Login Page

To make the WeChat login process better match your website’s look and feel, we also support another way to display the QR code on your page, using JavaScript.

First, include this line in your site’s <head> (this also supports HTTPS):

<script src="http://res.wx.qq.com/connect/zh_CN/htmledition/js/wxLogin.js"></script>

Next, in your code, instantiate WxLogin, passing the following parameters:

   var obj = new WxLogin({
          id:"login_container",
          appid: "",
          scope: "",
          redirect_uri: "",
          state: "",
          style: "",
          href: ""
      });
Parameters
Parameter Required Explanation
id Yes The container ID you wish to show the QR code within
appid Yes The ID registered for your application.
scope Yes Comma-delimited list of scopes authorized by user. For web login, use 'snsapi_login'
redirect_uri Yes The URL the user will be redirected to after authorization. Must be urlencoded.
state No This can be any state information you wish to preserve across the OAuth process, for instance a token to prevent CSRF attacks.
style No Either “black” or “white”, defaults to black.
href No See more info in the FAQ section at the bottom

gulp

Step 2: Passing the code to get the access_token

After the user is redirected back to your site, you can take the passed ‘code’ and call the access_token API as follows:

https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code

Important Note: Which URL to send my HTTP requests

Parameters
Parameter Required Explanation
appid Yes The ID registered for your application.
secret Yes The AppSecret as defined in the developer portal
code Yes The code parameter obtained previously
grant_type Yes Use “authorization_code
Response Fields

Example:

{   "access_token":"ACCESS_TOKEN",
    "expires_in":7200,
    "refresh_token":"REFRESH_TOKEN",
    "openid":"OPENID",
    "scope":"SCOPE",
    "unionid": "o6_bmasdasdsad6_2sgVt7hMZOPfL" }
Parameters
Parameter Explanation
access_token The access_token that you can now use when making other API calls.
expires_in The amount of time after which this token will expire, expressed in seconds.
refresh_token You can use this token to get a new access token, as defined below.
openid The unique identifier for this user
scope Comma-delimited list of scopes authorized by user. For web login, use 'snsapi_login'
unionid This field may be displayed only when the application has been authorized by users’ userinfo.

An error response will look something like this: {"errcode":40029,"errmsg":"invalid code"}

Refer to Return Codes.

Renewing your token

If an access token exceeds its validity period (typically 2 hours), there are two methods to renew it:

  1. If the token has already expired, call the refresh_token endpoint to get a new one.
  2. If the token has not yet expired, just call refresh_token to keep the same token but extend its validity.

The refresh_token's validity period is 30 days. After that, you will need to have the user re-authorize by scanning the login page QR code using WeChat.

Request Format

After obtaining a code, you can use this endpoint to get a new token.

Method: GET https://api.weixin.qq.com/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Important Note: Which URL to send my HTTP requests

Parameters
Parameter Required Explanation
appid Yes Your AppID used for development
grant_type Yes Use 'refresh_token'
refresh_token Yes The refresh_token obtained earlier when you got the initial access_token.
Response Format
{
    "access_token":"ACCESS_TOKEN",
    "expires_in":7200,
    "refresh_token":"REFRESH_TOKEN",
    "openid":"OPENID",
    "scope":"SCOPE"
}
Parameters
Parameter Explanation
access_token An access_token that you can now use for calling other APIs.
expires_in The validity period of this token.
refresh_token Another refresh_token you can use in the future.
openid The user's openid
scope Comma-delimited list of scopes authorized by user.

Step 3: Using your access_token

Here are all the APIs you can use:

Scope API endpoint Explanation
snsapi_base /sns/oauth2/access_token Get an access_token given a code (as described above)
snsapi_base /sns/oauth2/refresh_token Refresh an access_token given a refresh_token for a previously-authorized user (as described above)
snsapi_base /sns/auth Check the validity period of an access_token
snsapi_userinfo /sns/userinfo Get the user's profile info

FAQ

Q: What's code for?

A: The code parameter is used to obtain the access_token, which, after the user authenticates, can be used to call APIs. Your code is only valid for 10 minutes, to protect the security of the authentication process.

Q: What's scope for?

A: scope represents the privileges the third-party app has. You can apply for these privileges on the Official Account Admin site.

Q: In building a custom login page, how does the style parameter change the way the QR code appears?

A: There are two options you can use ("white" or "black"), depending on what best matches your custom login page's design.

Here's what they look like:

Black style login UI White style login UI

Q: On custom login pages, what's the href parameter for? How can I control its appearance?

A: This reminds the user what they're logging into. You can style it by adding custom CSS to the page like this:

.impowerBox .qrcode {width: 200px;}
.impowerBox .title {display: none;}
.impowerBox .info {width: 200px;}
.status_icon {display：none}
.impowerBox .status {text-align: center;}

Here's what that might look like:

Black style

WeChat Homepage Customer Support
Copyright © 1998- Tencent Inc. All rights reserved.
Terms of Service Privacy Policy Acceptable Use Policy