API documentation

Step 1: Create an AccessKey

API calls use an AccessToken for authentication. Create an AccessKey first, then exchange it for an access token.

A user AccessKey operates on data associated with that user. An administrator AccessKey operates on data that the administrator is permitted to manage. Choose the key type for the caller's identity.

User AccessKey: v0.2.1 and later

In the management interface, open “Platform users”, select the user's “Details”, then create a key under “API AccessKey”.

Self-service keys in the commercial edition

Commercial-edition users can also open “Access control” in the user portal and select “Create AccessKey”.

Administrator AccessKey: v0.2.3 and later

In the management interface, open “System users”, select the user's “Details”, then create a key under “API AccessKey”.

Step 2: Obtain an AccessToken

Send a POST request to /APIAccessTokenService/getAPIAccessToken with your AccessKey information. This endpoint obtains a token, so it does not require an existing X-Edge-Access-Token header.

Send JSON and set Content-Type: application/json. First confirm that the HTTP response status is 200, then check the code field in the response JSON. A JSON code of 200 means the token was obtained successfully; any other value indicates failure.

The request below uses an administrator identity. For a user AccessKey, change type to user and supply that user's own key information.

type

The caller's identity type: admin for an administrator, or user for a user.

accessKeyId

The ID of the AccessKey created in step 1.

accessKey

The secret associated with that AccessKey ID.

POST /APIAccessTokenService/getAPIAccessToken

{
  "type": "admin",
  "accessKeyId": "YOUR_ACCESS_KEY_ID",
  "accessKey": "YOUR_ACCESS_KEY"
}

{
  "code": 200,
  "data": {
    "token": "YOUR_ACCESS_TOKEN",
    "expiresAt": 1609686945
  },
  "message": "ok"
}

Token request examples with cURL

Replace the example IP address, port, YOUR_ACCESS_KEY_ID and YOUR_ACCESS_KEY with your own HTTP API endpoint and credentials. Administrators and users must use their corresponding AccessKey types.

curl -v -X POST \
  -H 'Content-Type: application/json' \
  'http://192.168.1.6:8004/APIAccessTokenService/getAPIAccessToken' \
  -d '{
    "type": "admin",
    "accessKeyId": "YOUR_ACCESS_KEY_ID",
    "accessKey": "YOUR_ACCESS_KEY"
  }'

curl -v -X POST \
  -H 'Content-Type: application/json' \
  'http://192.168.1.6:8004/APIAccessTokenService/getAPIAccessToken' \
  -d '{
    "type": "user",
    "accessKeyId": "YOUR_ACCESS_KEY_ID",
    "accessKey": "YOUR_ACCESS_KEY"
  }'

Token fields and expiration

When the token expires, call the token endpoint again.

Repeatedly obtaining tokens with the same AccessKey invalidates the previously issued AccessToken. After receiving a new token, use the latest token value for subsequent requests.

token

The access token. Send this value in the X-Edge-Access-Token HTTP header when calling other endpoints.

expiresAt

The token's expiration timestamp. Use the actual value returned by the API instead of assuming a fixed number of hours. The timestamp above only illustrates the response structure.

Step 3: Call an endpoint with the token

Find the required operation in the API directory and send the request to API_ENDPOINT/ServiceName/MethodName.

Use POST with a complete JSON request body and include the token returned in step 2 in the HTTP headers. Replace YOUR_ACCESS_TOKEN below with that value.

Content-Type: application/json
X-Edge-Access-Token: YOUR_ACCESS_TOKEN