Get and use API key

There is no limit to the number of API keys you can create in the EasyAR developer center. It is recommended to assign independent API keys to different applications for more granular permission control.

Create API key

Log in to the EasyAR Developer Center. If you are using an API key for the first time, please create one first by following these steps:

Under "Authorization," click "Cloud Service API KEY"
On the "API KEY" page, click the "Create API KEY" button

APIKey

Fill in the "Application Name"
Check the required cloud services according to your application needs. It is not recommended to authorize all services.
Click "Confirm"

Tip

To use SpatialMap, check SpatialMap.

To use Cloud Recognition, check Cloud Recognition.

To use Mega Landmark, check Mega Landmark. You need to apply for this feature through business channels before use.

To use AR Operations Center, check AR Operations Center. You need to apply for this feature through business channels before use.

To use Mega Block Cloud Localization, check Mega Block.

APIKey

The API Key and API Secret will then be generated on the page, as shown below. Be careful not to leak them.

APIKey

Warning

Do not use the API Key and API Secret directly on client-side applications (e.g., web, WeChat Mini Programs, etc.).

Get token

There are two ways to obtain a token: 1. Get it directly from the development center; 2. Write code to obtain it. If you need to control access to resources, it is recommended to use the second method. Below are the two acquisition methods, you can choose according to your needs.

Get token from the development center

Select an API Key you want to use, and click "Manage" on the right

APIKeyToken

Select a validity period for the token
Click "Generate Token"
Click "Copy" to complete

APIKeyToken

Note

Security is the primary reason for setting the token validity period. If the token validity period is too long, once leaked or stolen, attackers can use it for a long time, leading to data leakage or unauthorized operations. The validity period limits the effective window of the token, so even if it is leaked, the harm is limited to a short time.

Generate token using API key and API secret

The token generation process requires signing core parameters to ensure transmission security. These signed parameters are then sent to the STS (Security Token Service) for authentication. Once verified by the STS service, a temporary access token is issued, which is only valid within a specified time window. After expiration, the authentication process must be reinitiated.

Warning

Do not generate the token in client-side code. Instead, generate the token on the server side and pass it to the client for use.

Request parameters

Field name	Type	Required	Description
apiKey	string	Yes	API Key
expires	int	Yes	Generated token validity period, in seconds
acl	string	Yes	Access Control List, controls token's accessible resource permissions
timestamp	long	Yes	Timestamp, in milliseconds
signature	string	Yes	Signature

acl: Consists of one or more ACs (Access Control). Each AC contains four parts: service, effect, resource, permission.

service: Service type. Currently supports ecs:crs (cloud recognition), ecs:spatialmap (sparse spatial map), ecs:cls (Mega Block cloud-based localization), ecs:vps1 (landmark)
resource: Specific service's app id, e.g., CRS AppId for cloud recognition library
effect: Specifies whether access matching this resource configuration item can be executed. Values: Allow, Deny
permission: Permission values: READ, WRITE

Structure example:

[
  {
    "service": "ecs:crs",
    "resource": ["f7ff497727ab2d55ea01d9984ef8068c"],
    "effect": "Allow",
    "permission": ["READ"]
  }
]

Signature method

Sort all request parameters by key.
For each parameter, concatenate its key and value into a string.
Concatenate all the strings obtained in this way, and append the API Secret at the end.
Calculate the sha256 hash of the string in hexadecimal as the signature.

Signature example

<?php
// Your API Key and API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// Your service App ID
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Validity period, in seconds
$expires = 3600;

// Build parameters to be signed
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// Sort
ksort($data);

// Concatenate strings
$builder = [];
foreach ($data as $key => $value) {
    array_push($builder, $key . $value);
}

// Concatenate API Secret
array_push($builder, $apiSecret);

// Generate signature
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// Your API Key and API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// Your service App ID
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Validity period, in seconds
const expires = 3600

// Construct parameters to be signed
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// Sort and concatenate strings
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// Concatenate API Secret
builder.push(apiSecret);

// Generate signature
const signature = crypto.createHash('sha256').update(builder.join('')).digest('hex');
console.info(signature);

import time
import hashlib

# Your API key and API secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# Your service app ID
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# Expiration time in seconds
expires = 3600

# Build the parameters to be signed
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

# Concatenate the string
builder = [f'{key}{value}' for key, value in data.items()]

# Concatenate the API secret
builder.append(apiSecret)

# Generate the signature
signature = hashlib.sha256(''.join(builder).encode('utf8')).hexdigest()
print(signature)

package com.easyar;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.SortedMap;
import java.util.TreeMap;

public class App {

    public static void main(String[] args) throws NoSuchAlgorithmException {
        // Your API Key and API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // The App ID of the service
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // Expiration time in seconds
        int expires = 3600;

        // Build the parameters to be signed
        SortedMap<String, Object> data = new TreeMap<>();
        data.put("apiKey", apiKey);
        data.put("expires", expires);
        data.put("timestamp", System.currentTimeMillis());
        data.put("acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]");

        // Concatenate the string
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // Append the API Secret
        builder.append(apiSecret);

        // Generate the signature
        String signature = sha256(builder.toString());
        System.out.println(signature);
    }

    private static String sha256(String str) throws NoSuchAlgorithmException {
        StringBuilder builder = new StringBuilder();

        MessageDigest digest = MessageDigest.getInstance("sha-256");
        digest.update(str.getBytes(StandardCharsets.UTF_8));
        byte[] bytes = digest.digest();
        for (byte b : bytes) {
            String hex = Integer.toHexString(b & 0XFF);
            if (hex.length() == 1) {
                builder.append("0");
            }
            builder.append(hex);
        }

        return builder.toString();
    }
}

using System.Text;
using System.Security.Cryptography;

namespace EasyAR {
    static class Program {
        static void Main(string[] args) {
            // Your API Key and API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // App ID of the service
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // Validity period, in seconds
            int expires = 3600;

            // Build parameters to be signed
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

            // Concatenate strings
            StringBuilder builder = new StringBuilder();
            data.ToList().ForEach(pair => builder.Append($"{pair.Key}{pair.Value}"));

            // Append API Secret
            builder.Append(apiSecret);

            // Generate signature
            string signature = Sha256(builder.ToString());
            Console.WriteLine(signature);
        }

        static string Sha256(string str) {
            byte[] data = SHA256.HashData(Encoding.UTF8.GetBytes(str));
            StringBuilder builder = new StringBuilder();
            for (int i = 0; i < data.Length; i++) {
                builder.Append(data[i].ToString("x2"));
            }
            return builder.ToString();
        }
    }
}

package main

import (
    "crypto/sha256"
    "fmt"
    "sort"
    "strings"
    "time"
)

func main() {
    // Your API Key and API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // Your service App ID
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // Expiration time in seconds
    expires := 3600

    // Construct parameters to be signed
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

    // Sort
    keys := []string{}
    for key := range data {
        keys = append(keys, key)
    }
    sort.Strings(keys)

    // Concatenate strings
    builder := strings.Builder{}
    for _, key := range keys {
        builder.WriteString(fmt.Sprintf("%s%v", key, data[key]))
    }

    // Concatenate API Secret
    builder.WriteString(apiSecret)

    // Generate signature
    signature := fmt.Sprintf("%x", sha256.Sum256([]byte(builder.String())))
    fmt.Println(signature)
}

Tip

When adding a signature, the ACL needs to be converted to a JSON string.

Get the token

Add the generated signature to the parameter list and send a request to the /token/v2 interface to obtain the token.

Request address: https://uac.easyar.com/token/v2 or https://uac-na1.easyar.com/token/v2 (North America Zone 1)
Request method: POST
Request header: Content-Type: application/json
Request parameters: {"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Example:

curl -X POST https://uac.easyar.com/token/v2 \
-H 'Content-Type: application/json' \
-d '{"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}'

If the statusCode in the response is 0, it indicates success.

Normal response format:

{
  "statusCode": 0,
  "timestamp": 1765954874399,
  "msg": "Success",
  "result": {
    "apiKey": "6a47f7f8ff6......68744b4bcf",
    "expires": 3600,
    "token": "nuPDCj......xstQX",
    "expiration": "2025-12-17T08:01:14.399+0000"
  }
}

token: The token for business request authentication.
expiration: The expiration time of the token. A new token must be requested after expiration.

Error response format:

{
  "statusCode": 4001017,
  "timestamp": 1765954666624,
  "msg": "AppId is not authorized by this API Key",
  "result": null
}

Using token

In business HTTPS requests, add the token to the request header in the format: {"Authorization": "nuPDCj......xstQX"}.

When sending business API requests, the parameter appId must be included (refer to the development center for the source of obtaining it).

Error code description

During the process of token generation and token usage, various errors or exceptions may occur.
To help developers quickly locate issues and take effective solutions, the following details common error codes and their meanings:

Error Code	Error Message	Error Description	Solution
4001011	API Key invalid	API Key is invalid	Check if this API Key exists under "Cloud Service API KEY"
4001012	Timestamp invalid	Timestamp is invalid	The timestamp unit is milliseconds, and the deviation from standard time should not exceed 5 minutes
4001015	Signature invalid	Signature is invalid	Verify the signature algorithm is correct and check if the API Secret matches the API KEY
4001017	AppId is not authorized by this API Key	API Key is not authorized for this AppId	Check if the service where the AppId is located is associated with this API Key
4001018	Base64 decode error	The Authorization set in the request header is not in a valid base64 format	Do not process the obtained token in any way; use it directly
4001019	Decryption error	The Authorization set in the request header is not generated by EasyAR	Do not process the obtained token in any way; use it directly
4001022	API Key's resource is empty	API Key has no associated cloud service	Check if the API Key is associated with a cloud service and if the associated cloud service has expired
4001024	Token is expired	Token has expired	Regenerate the token
4001025	Token generate fail	Token generation failed	Contact technical support: support@easyar.com

Table of Contents

Get and use API key

Create API key

Tip

Warning

Get token

Get token from the development center

Note

Generate token using API key and API secret

Warning

Request parameters

Signature method

Signature example

Tip

Get the token

Using token

Error code description