User authorized login

DotWallet provides familiar oAuth login and authorization. The user can authorize the app to access certain basic user information.

Step 1: Prompt user to authorize and get code

The code is used to exchange for an access_token. Each time the user completes an authorization, the code will be a new, different code. The code can only be used once and will expire if not used within 5 minutes.

Redirect the browser view to the following URL, with the following parameters to show the user authorization prompt:

Param Required Description
app_id YES Application ID
redirect_uri YES URL to redirect to after authorization

The DotWallet authorization page
Authorize

If the user agrees to authorize, the page will redirect to {redirect_uri}/?code={code}

If the user refuses to authorize, then they will also be redirected to the redirect page, but without the code

Failure example:

{
  "code": 10003,
  "msg": "redirect_uri is inconsistent with previous setting."
  }
}

Step 2: Use code to get access token

Important:

  • secret and access_token are sensitive, high security information and must only be saved on the server and never sent to the client.
  • Subsequent steps such as refreshing access_token and obtaining user information through access_token must also be initiated from the server.
Param Required Description
app_id YES Application ID
secret YES Application secret key
code YES The code from step one

Example request:

curl --location --request POST 'https://www.ddpurse.com/openapi/access_token' \
--header 'Content-Type: application/json' \
--data-raw '{
	"app_id":"0d158bc3605fffef7046f0c9c7e4bf",
	"secret":"e9943b6b167554f55e39c1428c1d86",
	"code":"593f40971422015be811f8526970436f5326b5371a514ca5c45b53bc4ec85039"
}

Success:

Note: "code" here is the error response code. 0 means success

{
  "code": 0,
  "msg": "",
  "data": {
    "access_token": "ACCESS_TOKEN",
    "expires_in": 7200,
    "refresh_token": "REFRESH_TOKEN"
  }
}

Failure example:

{
  "code": 10017,
  "data": {},
  "msg": "Login error, invalid code"
}

Return params description:

Param Type Description
access_token string Access token
expires_in int Time until access token expiry (unit: seconds)
refresh_token string Token used to refresh access_token (see below for more details)

Step 3: Get user information

Param Type Required Description
access_token string YES The access_token from step 2

Success:

Note: "code" here is the error response code. 0 means success

{
  "code": 0,
  "msg": "",
  "data": {
    "user_open_id": "USER_OPEN_ID",
    "user_name": "USER_NAME",
    "user_avatar": "USER_AVATAR",
    "user_address": "1BNPUQAGjAmW9m8cK3HV4Xp3GZLnW1UZ99",
    "pay_status": 1,
    "pre_amount": 800,
    "total_amount": 12000
  }
}

Failure example:

{
  "code": 10021,
  "msg": "login error, error retrieving user information, error code: 10021",
  "data": {}
}

Return params description:

Param Description
user_open_id Global user ID
user_name User's name
user_avatar User's avatar (image URL)
user_address User's wallet receiving address
pay_status Whether to authorize automatic micropayments (0:NO, 1:YES)
pre_amount Maximum amount for single automatic micropayments
total_amount Maximum sum value of cumulative automatic micropayments

Refresh token

Because access_token has a short validity period (7200 seconds), when access_token expires you can use refresh_token to refresh. refresh_token will expire in 30 days. When refresh_token expires, the user needs to re-authorize。

Param Type Required Description
app_id string Application ID
refresh_token string Refresh token from step 2

Success:

Note: "code" here is the error response code. 0 means success

{
  "code": 0,
  "msg": "",
  "data": {
    "access_token": "ACCESS_TOKEN",
    "expires_in": 7200,
    "refresh_token": "REFRESH_TOKEN"
  }
}

Failure example:

{
  "code": 10303,
  "msg": "refresh access_token error",
  "data": {}
}

Return params description:

Param Type Description
access_token string Access token
expires_in int Time until access token expiry (unit: seconds)
refresh_token string Refresh token

Validate token

Param Required Description
access_token YES Access token

Success:

Note: "code" here is the error response code. 0 means success

{
  "code": 0,
  "msg": "",
  "data": {
    "status": 1,
    "expire_time": 4010
  }
}

Failure example:

{
  "code": 10021,
  "msg": "Login error, user_open_id can not be null",
  "data": {}
}

Return params description:

Param Description
code Error code
status Token validation status (0: not existent, -1: expired, 1: ok)
expire_time Time until access token expiry (unit: seconds)