Authoring OAuth App

The flow of OAuth authorization is as follows:

1. Users are redirected to request their Guizhan Account authorization.
2. Users are redirected back to your app.
3. Your app accesses our API with user’s access token.

1. Request authorization

GET https://account.guizhanss.com/oauth/authorize

This endpoint takes following query parameters:

Query parameter	Type	Required?	Description
client_id	string	Required	The client ID you received after creating OAuth app.
redirect_uri	string	Required	The redirect URI of your OAuth App. It must exactly match one of the registered redirect_uris (multiple URIs may be registered).
scope	string	Context dependent	A comma-delimited list of scopes. See Scopes for more information.
state	string	Recommended	An unguessable random string. It is used to protect against cross-site request forgery attacks.

2. Users are redirected back

If the user accepts your request, Guizhan Account redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step. The temporary code will expire after 10 minutes. If the states don’t match, then a third party created the request, and you should abort the process.

If authorization is aborted, the user is redirected back to your site with a code parameter and message parameter explaining the reason. Check API error codes for more information

Exchange access token with the given code:

POST https://account.guizhanss.com/oauth/token

This endpoint takes following parameters:

Parameter	Type	Required?	Description
grant_type	string	Optional	Must be authorization_code; defaults to authorization_code.
client_id	string	Required	The client ID you received after creating OAuth app.
client_secret	string	Required	The client secret you received after creating OAuth app.
code	string	Required	The temporary code you received after authorization.
redirect_uri	string	Required	The redirect URI of your OAuth App. It must exactly match the redirect URI provided in the authorization request.

Caution

This endpoint only accept content type of application/x-www-form-urlencoded. JSON content is not permitted and will return an error.

You will get a similar JSON response as follows:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "expires_in": 1800,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "user:email"
}

To refresh an access token, send a form-encoded request:

POST https://account.guizhanss.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=user:email

The scope parameter is optional and can only narrow the scope of the new access token.

OAuth errors use the standard error response structure:

{
  "error": "invalid_grant",
  "error_description": "The refresh token is invalid."
}

3. Use access token to access our API

The access token allows you to make requests to our API on behalf of the user.

Authorization: Bearer OAUTH-TOKEN

Scopes

The scope parameter is context dependent.

If scope parameter is left out, The For example, if the user has already authorized your app with user:read scope, and you provide user:update scope, the final scope will be user:read,user:update.

If scope parameter is left out and the user has already authorized your app, the existing scopes will be used.

See Scopes for available scopes.