街旁API开发文档

首页 > 开发文档 > OAuth 说明

简介

街旁开放API使用OAuth 2.0作为第三方应用授权和验证的方式。与OAuth 1.0相比，您实现基于OAuth 2.0的应用会更简单。

验证授权方式

街旁网目前支持两种验证授权方式：从服务器端调用（叫做Authorization Code）和从客户端调用（叫做Implicit Grant）。根据您的应用类型和需求，您可以选择一种合适的验证授权方式。

方式一：从服务器端调用（Authorization Code）

此授权方式适用于有服务器的应用，例如：Web站点、有服务器的客户端应用等。

第一步：获取Authorization Code

要获取Authorization Code，应用需要先将用户浏览器重定向到授权页面：

https://jiepang.com/oauth/authorize?response_type=code&client_id=YOUR_APP_ID&redirect_uri=YOUR_URL&state=ABCDEFG

response_type
- 必需参数。此处的值必须为“code”。
client_id
- 必需参数。为注册应用时获得的App ID。
redirect_uri
- 必需参数。为授权后要跳转到的URL。
state
- 非必需参数。您的应用可将此参数的值设置为任意的字符串，在第二步会原样返回此字符串。可用于保存用户状态等信息。

当用户授权了您的应用后，页面会回调到以下URL：

YOUR_URL?code=XXXXYYYYZZZZ&state=ABCDEFG

code
- 为Authorization Code，有效期为5分钟，并且只能使用一次，再次使用将无效。
state
- 与请求中的state参数值一致。

如果发生错误或用户拒绝授权，会跳转到以下URL：

YOUR_URL?error=ERROR_TYPE&error_description=ERROR_DESCRIPTION&state=ABCDEFG

error:
- 错误类型，可能有以下值：
  - invalid_request
  - unauthorized_client
  - access_denied
  - unsupported_response_type
  - invalid_scope
  - server_error
  - temporarily_unavailable
error_description
- 错误的详细描述文字，以UTF-8编码。
state
- 与请求中的state参数一致。

第二步：获取Access Token

要获取Access Token，需要在服务器端向以下地址发送请求：

https://jiepang.com/oauth/token?grant_type=authorization_code&code=XXXYYYZZZ&client_id=YOUR_APP_ID&client_secret=YOUR_APP_SECRET&redirect_uri=YOUR_URL

grant_type
- 必需参数。此处的值必须为“authorization_code”。
code
- 必需参数。值为上一步返回的Authorization Code。
client_id
- 必需参数。为注册应用时获得的App ID。
client_secret
- 必需参数。为注册应用时获得的App Secret。
redirect_uri
- 必需参数。必须和第一步里的redirect_uri参数一致。

若参数无误，服务器将返回以下JSON数据：


							
							{
							"access_token": "AAABBBCCCDDD"
							}

access_token
- 要获取的Access Token。

如果发生错误，会返回以下JSON数据：


							{
								"error": "ERROR_TYPE",  

									 "error_description": "ERROR_DESCRIPTION"
								
								}

error
- 错误类型，可能有以下值：
  - invalid_request
  - invalid_client
  - invalid_grant
  - unauthorized_client
  - unsupported_grant_type
  - invalid_scope
error_description
- 错误的详细描述文字。

方式二：从客户端调用（Implicit Grant）

此授权方式适用于无服务器或不能在服务器保存信息的应用，例如：桌面程序、浏览器插件、纯JavaScript应用等。
要获取Access Token，应用需要将用户浏览器重定向到授权页面：

https://jiepang.com/oauth/authorize?response_type=token&client_id=YOUR_APP_ID&redirect_uri=YOUR_URL&state=ABCDEFG

response_type
- 必需参数。此处的值必须为“token”。
client_id
- 必需参数。注册应用时获得的App ID。
redirect_uri
- 必需参数。授权后要回调的URL。
state
- 非必需参数。可设置为任意的字符串，在第二步会原样返回此字符串。可用于保存用户状态等信息。

当用户授权了您的应用后，会跳转到以下URL：

YOUR_URL#access_token=AAABBBCCCDDD&state=ABCDEFG

access_token
- response_type
state
- 与请求中的state参数一致。

如果发生错误，会跳转到以下URL：

YOUR_URL#error=ERROR_TYPE&error_description=ERROR_DESCRIPTION&state=ABCDEFG

error
- 错误类型，可能有以下值：
  - invalid_request
  - invalid_client
  - access_denied
  - unsupported_response_type
  - invalid_scope
  - server_error
  - temporarily_unavailable
error_description
- 错误的详细描述文字。
state
- 与请求中的 state 参数一致。