Access Token

When calling the server-side API, the access token is used for authorization. For security reasons, the access token will expire after 8 hours. The user needs to update the access token after it's expired using refresh token . Access token, refresh token will be returned when the authorized API is called.

Get access token, refresh token

The user needs to post App ID and App Secret of the application to the authorization API to get the access token and refresh token.

Request example

In this document，API_HOST=https://maptable.com

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

Request body example

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

Python example

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()

Response

Response body

Name	Type	Description
detail	object
∟ token	string	access token
∟ refreshToken	string	refresh token

Response body example

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

Refresh the access token with refresh token

Posting the refresh token to the refresh token API, the server will generate a new access token and refresh token pair.

Request

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

Request body example

{
    "refreshtoken": "bibxxjvzhm04"
}

Python example

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()

Response

Response body

Name	Type	Description
detail	object
∟ token	string	access token
∟ refreshToken	string	refresh token

Response body example

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

Use access token to call API

To call the API (except token-related), the user needs to set the access token in the header. The following is an example of API call to list workspaces.

Request

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

Python example

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()

Response

The return of the API, which generally includes code, message and detail.

Name	Type	Description
code	int	Error code, non-zero code means error happens.
message	string	The description of error if any.
detail	object	The response body.

Response body example

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

Request frequency control

All APIs are limited to a maximum frequency of 60 requests per application per minute.