Miaozhen API Authentication

---

Your application need an access token when access Miaozhen API. The access tokens are granted by Miaozhen OAuth2 Service and will be expired in short time (1 hour by default).

The grant workflow follows OAuth 2.0 specification. Currently the following grant types are supported:

• password: RFC6749, Section-4.3 Resource Owner Password Credentials Grant
• client_credentials: RFC6749, Section-4.4 Client Credentials Grant

Generally speaking, when your app is requesting access to the protected resources in the name of a specific user with the password, you should use password grant. When your app is requesting access to the resources not related to a user (e.g. meta data, public data), you should follow client_credentials grant.

In password grant, you can also obtain a refresh token. It is a long-lasting (1 month by default) credential and can be used to refresh the access token (RFC6749, Section-6 Refreshing an Access Token).

More information about access token requests for supported grant types and refreshing:

• Token Request - passwordAvailable

• Token Reqeust - client_credentials Unavailable

• Token Request - refresh_token Unavailable

More information about access token responses:

• Token Response

Note

• All access token grants should be done in a server-to-server manner to protect your client_id and client_secret.

• If you do not know your client_id / client_secret or username / password, inquire Miaozhen account executive team.

---

Token Request - password Available

You need to send a access token request (HTTP POST) to the endpoint:

https://api.cn.miaozhen.com/oauth/token

In the access token request body, the grant_type must be password. You must present username and password of the user’s Miaozhen account you want to access, as well as client_id and client_secret to authenticate your application.

• Example Access Token Request

  POST /oauth/token HTTP/1.1
  Host: api.cn.miaozhen.com
  Content-Type: application/x-www-form-urlencoded
  grant_type=password&username=john&password=8888&client_id=1234&client_secret=7Fjfp0ZBr1KtDRbn

Token Request - client_credentials Unavailable

You need to send a access token request (HTTP POST) to the endpoint:

https://api.cn.miaozhen.com/oauth/token

In the access token request body, the grant_type must be client_credentials. You must present client_id and client_secret to authenticate your application.

• Example Access Token Request

  POST /oauth/token HTTP/1.1
  Host: api.cn.miaozhen.com
  
  Content-Type: application/x-www-form-urlencoded
  grant_type=client_credentials&client_id=1234&client_secret=7Fjfp0ZBr1KtDRbn
  

Token Request - refresh_token Unavailable

You need to send a access token request (HTTP POST) to the service endpoint:

https://api.cn.miaozhen.com/oauth/token

In the access token request body, the grant_type must be refresh_token. You must present client_id and client_secret to authenticate your application, as well as refresh_token.

• Example Access Token Request

  POST /oauth/token HTTP/1.1
  Host: api.cn.miaozhen.com
  
  Content-Type: application/x-www-form-urlencoded
  grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=1234&client_secret=7Fjfp0ZBr1KtDRbn
  

Token Response

If succeeds, the server returns a JSON object with a 200 (OK) status code. The JSON contains the following parameters,access_token, token_type, expires_in and scope. The scope is a space-delimited list specifying all the API categories granted.

For password grant, there is one additional parameter refresh_token in response which can be used to refresh access token.

By default, an access token will expire in 1 hour, an refresh token will expire in 1 day.

• Example Successful Response

  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  
  {
    "access_token": "1.2YotnFZFEjr1zCsi",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "cms admonitor",
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
  }
  

If failed, the server responds a JSON error object with an HTTP 400 (Bad Request) status code. The JSON contains an error parameter as error code and optionally an error_description. See RFC6749 “5.2. Error Response” in detail.

• Example Error Response

  HTTP/1.1 400 Bad Request
  Content-Type: application/json;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  
  {
    "error": "invalid_request",
    "error_description": "Some human-readable text providing
   additional information."
  }