中文 | English
Home > Document > Authorization Flow Description

Authorization Flow Description

Guidance

I. Introduction

II. Service-side Flow

III. Native Application

IV. Application Authenication and Authorization Flow

V. API Calling via OAuth 2.0

VI. Authorization Validity Duration

VII. Interface Description

I. Introduction

After your APP is interconnected to VOP, it is necessary to obtain restrictedly accessible private data (such as: goods, orders, etc.) of users (including vendors). In order to ensure the security of user data and privacy, your APP is required to obtain the user's authorization in this case, your application needs to guide the user through the process of "use VIP account to sign in and authorize".

The OAuth2.0 agreement is used in the current authorization process. If you want to know more technical details about the protocol, please see the official description: http://oauth.net/2/. If you are an ISV, you need to guide the user to the authorization page, and the user should have a VIP account and password. Binding authentication the account with vendor’s ID is completed together. The steps are as follows:

  1. ISV carries out APP review and sandbox joint debugging.

  2. The vendor using ISV software carries out [Vendor Identity Authentification Flow] Process in VOP site(http://vop.vip.com/doccenter/viewdoc/34 "Vendor Identity Authentification Flow")

  3. ISV software guides the vendor to complete the authorization.

  4. The vendor begins to use ISV software normally.

You may select an applicable authorization flow as per your application scenario:

Server-side flow: this is suitable for Web application; it requires ISV APPs are provided with Web Server APPs, able to store APP’s keys and status and directly accessible to servers via https.

Native Application: this is suitable for Mobile application; meanwhile, the APP cannot interact with the browser, but you can call outside browsers.

II. Server-side flow

The flow is suitable for Web application; it requires ISV APPs are provided with Web Server APPs, able to store APP’s keys and status and directly accessible to servers via https. The authorization process consists of two steps OAuth 授权图2.png 1) Guide user requiring for authorization to the following link; https://auth.vip.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI If the user agrees to authorize, the page will jump to YOUR_REGISTERED_REDIRECT_URI/?code=CODE

2) Get access token (http Post )
https://auth.vip.com/oauth2/token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&request_client_ip=127.0.0.1&code=CODE
The return value includes the access token, which is used to call API.

Example: 1. Login page
User's operation: the user enters VIP account, password and CAPTCHA for login.
2015-05-01至2015-05-26api调用统计(1).png 2. Authorization page User's operation: Authorize or cancel web-grand.png if the user clicks "authorize", the page will jump to the callback link, which is attached to the code. The APP may get access token via getting and using this code. pc-grand-success.png If the user clicks "Cancel", it will jump to the callback link, which is attached to error as error code; error_description is description of errors. web-reject.png

III. Native Application

This is suitable for Mobile application; meanwhile, the APP cannot interact with the browser, but you can call outside browsers. When redirect_uri=urn:ietf:wg:oauth:2.0:oob occurs, the Native Application flow is called.

Authorization flow:

  1. Obtain authorization code:https://auth.vip.com/oauth2/authorize

  2. Exchange access token:https://auth.vip.com/oauth2/token
    Example

1)Request login for authorization https://auth.vip.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=urn:ietf:wg:oauth:2.0:oob&state=1212&display=mobile User's operation: the user enters VIP account, password and captcha for login.

登录_mmobile.jpg

2)Request the user for authorization
User's operation: Authorize or cancel mobile_grand.png
If "Authorize" is clicked, the page will call back to the default page. Meanwhile, the authorization mobile-reject.png

3)Get access token.

IV. Application Authentication and Authorization Flow

Guide the user requiring for authorization to the following link:
https://auth.vip.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
If the user agrees to authorize, the page will jump to YOUR_REGISTERED_REDIRECT_URI/?code=CODE
Get Access Token
https://auth.vip.com/oauth2/access_token? client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&request_client_ip=127.0.0.1&code=CODE
The return value includes the access token
The obtained access token is used for calling API.

V. API Calling via OAuth 2.0

Pass the parameter directly, with parameter name access_token
http://myi.vip.com/api/account/info?access_token=abcd

VI. Authorization Validity Duration

When the program calls the interface, it is required to determine the return value of interface. If the user's access token is invalid, it needs to guide the user for authorization again. The reasons for invalidity include: The user cancels the corresponding authorization. The access token expires naturally. It is valid for 30 days.
The user changes the password and thus freezes the corresponding authorization.
VIP freezes the user's corresponding authorization for the user's account which is found stolen.

VII. Interface Descriptions

Interface Description
OAuth2/authorize Request user for authorization token
OAuth2/token Get authorized access token
OAuth2/token_info Authorize information query interface
OAuth2/revoke_token Authorize recycle interface

/oauth2/authorize

1) Description request used for authorization token
2) URL https://auth.vip.com/oauth2/authorize
3) HTTP request mode GET
4) Request parameters
11.png 5) Return data
无标题.png 6) Example
//Request:
https://auth.vip.com/oauth2/authorize? client_id=0123456789&response_type=code&redirect_uri=http://myi.vip.com/index.html
//redirect after agreement of authorization:http://myi.vip.com/index.html&code=23456

/oauth2/token

1) Description get authorized access token
2) URL https://auth.vip.com/oauth2/token
3) HTTP request mode POST
4) Request parameters
21.png

5) Return data
22.png 6) Example
//Request:
https://auth.vip.com/oauth2/token? grant_type=authorization_code&client_id=12345&client_secret=abcde&redirect_uri=myi.vip.com/index.h tml&request_client_ip=127.0.0.1&code=23456
//return to result: {
"access_token": "63945DC",
"expires_in": 12340,
"open_id": "69BA0D4"
}

/oauth2/token_info

1) Description authorize information query interface 2) URL https://auth.vip.com/oauth2/token_info
3) HTTPrequest mode POST
4) Request parameters 31.png 5) Return data
32.png 6) Example
//Request:
https://auth.vip.com/oauth2/token_info?access_token=63945DC
//normally return to result:
{
"access_token": "63945DC4F3A5AA8DF537833900713E8341EF430C",
"create_at": "2015-03-13 17:24:20",
"expires_in": 12340,
"expires_time": "2015-03-13 20:50:00",
"open_id": "69BA0D43AF9E3821EE93F72D3BB14724",
"token_type": "Bearer"
}
//If token has been recycled
{
"code": 0,
"msg": "token revoked"
}

/oauth2/revoke_token

1) Description Authorize recycle interface 2) URL https://auth.vip.com/oauth2/revoke_token
3) HTTP request mode POST
4) Request parameters
41.png 5) Return data
42.png 6) Example
//Request:
https://auth.vip.com/oauth2/ revoke_token?access_token=63945DC
//normally return to result:
{
"code": 0,
"msg": "success"
}
// If token is invalid
{
"code": 30111,
"msg": "access token invalid"
}