访问凭证 Access Token

调用服务端API时，需要通过access token来鉴定调用者身份，以此进行授权。出于安全因素考虑，access token 需要设定一个过期时间(8小时); 在 access token 失效之后，可以通过刷新 API 使用 refresh token 来更新 access token。Access token、refresh token 会在调用授权 API 时返回。

获取 access token、refresh token

调用服务端授权API，提供应用的App ID 和 App Secret，获取app_access_token

请求示例

在本文档中，API_HOST=https://maptable.com

curl -vvv "$API_HOST/open/api/v1/auth/" -H "Content-Type: application/json" -d '$request_body'

请求体示例

{
    "appId": "appid-in-profile-page",
    "appSecret": "6d3a45095e1127d99338f668ccec1f35ff60148a"
}

Python 示例

def get_access_token(app_id, app_secret):
    url = '%s/open/api/v1/auth/' % API_HOST
    data = {
        'appId': app_id,
        'appSecret': app_secret
    }
    req = requests.post(url, json=data)
    return req.json()

响应

响应体

名称	类型	描述
detail	object
∟ token	string	access token
∟ refreshToken	string	refresh token

响应体示例

{
    "code": 0,
    "detail": {
        "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refreshToken": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "extra":null,
    "message": "OK",
    "requestID":null
}

使用 refresh token 刷新 access token

调用服务端授权API，提供应用的App ID 和 App Secret，获取app_access_token

请求

curl -vvv "$API_HOST/open/api/v1/token/refresh/" -H "Content-Type: application/json" -H "Authorization: $refresh-token" -d '$request_body'

请求体示例

{
    "refreshtoken": "bibxxjvzhm04"
}

Python 示例

def refresh_access_token(refresh_token):

    url = '%s/open/api/v1/token/refresh/' % API_HOST
    data = {
        'refreshtoken': refresh_token,
    }
    headers = {'Authorization': refresh_token}
    req = requests.post(url, json=data, headers=headers)
    return req.json()

响应

API 的返回结果，一般包括了 code, message 和 detail。

名称	类型	描述
code	int	错误码，非 0 表示失败
message	string	错误描述
detail	object	返回的响应数据

响应体示例

{
    "code": 0,
    "detail": {
        "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refreshToken": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "extra":null,
    "message": "OK",
    "requestID":null
}

使用 access token 调用 API

调用（除 token 相关的） API，需要在 header 中设置 access token，下面以列出工作区的 API 为例，介绍 API 调用方法

请求

curl -vvv "$API_HOST/open/api/v1/workspaces/" -H "Content-Type: application/json" -H "Authorization: $access-token"

Python 示例

def openapi_list_workspaces(access_token):
    url = '%s/open/api/v1/workspaces/' % API_HOST
    headers = {'Authorization': access_token}
    req = requests.get(url, headers=headers)
    return req.json()

响应

API 的返回结果，一般包括了 code, message 和 detail。

名称	类型	描述
code	int	错误码，非 0 表示失败
message	string	错误描述
detail	object	返回的响应数据

响应体示例

{
  "code": 0,
  "detail": [
    {
      "id": 164,
      "name": "580****9080",
      "type": "user",
      "avatar": null,
      "plan": "base"
    }
  ],
  "extra": null,
  "message": "OK",
  "requestID": null
}

请求频率控制

所有接口限制每个应用最高频率 60 次/分钟