Obter e usar API Key

No EasyAR Developer Center não há limite para a criação de API Key. Recomenda-se atribuir API Key independente a diferentes aplicações para controlar permissions de forma mais refinada.

Criar API Key

Faça login no EasyAR Developer Center. Se for a primeira vez que usa API Key, crie primeiro uma API Key:

Em "Authorization", clique em "Cloud Service API KEY"
Na página "API KEY", clique no botão "Create API KEY"

APIKey

Preencha "Application Name"
Selecione os cloud services necessários conforme as necessidades da aplicação. Não é recomendado autorizar todos.
Clique em "OK"

Dica

Ao usar SpatialMap, selecione SpatialMap.

Ao usar Cloud Recognition, selecione Cloud Recognition.

Ao usar Mega Landmark, selecione Mega Landmark; é necessário solicitar ao comercial antes de usar esta função.

Ao usar AR Operation Center, selecione AR Operation Center; é necessário solicitar ao comercial antes de usar esta função.

Ao usar Mega Block cloud localization, selecione Mega Block.

APIKey

Nesse momento, API Key e API Secret serão gerados na página conforme mostrado abaixo. Tenha cuidado para não divulgá-los.

APIKey

Aviso

Não use API Key e API Secret diretamente em aplicações client, como Web ou WeChat Mini Program.

Obter Token

Há duas formas de obter Token: 1. obter diretamente pelo Developer Center; 2. obter por código. Se você precisa controlar permissions de acesso a resources, recomenda-se a segunda forma. As duas formas são descritas abaixo.

Obter Token pelo Developer Center

Selecione uma API Key para usar e clique em "Manage" à direita

APIKeyToken

Selecione um período de validade do Token
Clique em "Generate Token"
Clique em "Copy"

APIKeyToken

Nota

Segurança é o principal motivo para configurar a validade do Token. Se a validade for longa demais, uma vez vazado ou roubado, um invasor poderá usá-lo por muito tempo, causando vazamento de dados ou operações não autorizadas. A validade limita a janela efetiva do Token; mesmo que vaze, o dano fica limitado a pouco tempo.

Gerar Token com API Key e API Secret

O processo de geração de Token exige assinar os parâmetros principais para garantir a segurança da transmissão. Depois, os dados assinados são enviados ao serviço STS (Security Token Service) para autenticação. Após a verificação pelo STS, é emitido um access Token temporário válido apenas na janela de tempo especificada; após expirar, é necessário iniciar novamente a autenticação.

Aviso

Não gere Token no client code; gere no server side e depois envie ao client para uso.

Parâmetros de request

Nome do campo	Tipo	Obrigatório	Descrição
apiKey	string	Sim	API Key
expires	int	Sim	Tempo de validade do Token gerado, em segundos
acl	string	Sim	Access Control List, controla as permissões de resource acessíveis pelo token
timestamp	long	Sim	Timestamp, em milissegundos
signature	string	Sim	Signature

acl: é composto por um ou mais AC (access control). Cada AC contém quatro partes: service, effect, resource e permission.

service: tipo de serviço; atualmente suporta ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Localization), ecs:vps1 (landmark)
resource: app id do serviço específico, por exemplo CRS AppId da Cloud Recognition library
effect: especifica se o acesso correspondente a esta configuração de resource pode ser executado; valores Allow, Deny
permission: valores de permissão READ, WRITE

Exemplo de estrutura:

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

Método de signature

Ordene todos os parâmetros da request pelo key name
Para cada parâmetro, concatene key name e value em uma string
Concatene todas as strings obtidas e acrescente API Secret no final
Calcule o sha256 hash da string; o valor hexadecimal é a signature

Exemplo de signature

<?php
// sua API Key e seu API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// App ID do seu servico
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// tempo de validade, em segundos
$expires = 3600;

// constroi os parametros a serem assinados
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// ordena
ksort($data);

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

// concatena o API Secret
array_push($builder, $apiSecret);

// gera a assinatura
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// sua API Key e seu API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// App ID do seu servico
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// tempo de validade, em segundos
const expires = 3600

// constroi os parametros a serem assinados
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// ordena e concatena a string
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// concatena o API Secret
builder.push(apiSecret);

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

import time
import hashlib

# sua API Key e seu API Secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# App ID do seu servico
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# tempo de validade, em segundos
expires = 3600

# constroi os parametros a serem assinados
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

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

# concatena o API Secret
builder.append(apiSecret)

# gera a assinatura
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 {
        // sua API Key e seu API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // App ID do servico
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // tempo de validade, em segundos
        int expires = 3600;

        // constroi os parametros a serem assinados
        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\"]}]");

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

        // concatena o API Secret
        builder.append(apiSecret);

        // gera a assinatura
        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) {
            // sua API Key e seu API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // App ID do servico
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // tempo de validade, em segundos
            int expires = 3600;

            // constroi os parametros a serem assinados
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

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

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

            // gera a assinatura
            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() {
    // sua API Key e seu API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // App ID do seu servico
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // tempo de validade, em segundos
    expires := 3600

    // constroi os parametros a serem assinados
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

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

    // concatena o API Secret
    builder.WriteString(apiSecret)

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

Dica

Ao adicionar a signature, ACL precisa ser convertido para string JSON.

Obter Token

Adicione a signature gerada acima à lista de parâmetros e envie a request para a interface /token/v2 para obter Token.

Endereço da request: https://uac.easyar.com/token/v2 ou https://uac-na1.easyar.com/token/v2 (North America 1)
Método da request: POST
Header da request: Content-Type: application/json
Parâmetros da request:{"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Exemplo:

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"}'

Se statusCode no resultado retornado for 0, significa sucesso.

Formato de retorno normal:

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

token: Token para autenticação da business request.
expiration: horário de expiração do token; após expirar, é necessário solicitar o token novamente.

Formato de retorno de erro:

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

Usar Token

Em requests https de negócio, adicione Token ao request header no formato: {"Authorization": "nuPDCj......xstQX"}.

Ao enviar business API request, é necessário adicionar o parâmetro appId (consulte o service correspondente no Developer Center para a origem).

Descrição dos error codes

Durante a geração e o uso de Token podem ocorrer diversos errors ou exceptions. Para ajudar developers a localizar problemas rapidamente e tomar medidas eficazes, os error codes comuns e seus significados são detalhados abaixo:

Error code	Error message	Descrição do erro	Solução
4001011	API Key invalid	API Key inválida	Verifique se esta API Key existe em "Cloud Service API KEY"
4001012	Timestamp invalid	Timestamp inválido	A unidade do timestamp é milissegundos e a diferença em relação ao horário padrão não deve exceder 5 minutos
4001015	Signature invalid	Signature inválida	Verifique se o algoritmo de signature está correto e se API Secret corresponde a API KEY
4001017	AppId is not authorized by this API Key	API Key não autorizou este AppId	Verifique se o service ao qual AppId pertence está associado a esta API Key
4001018	Base64 decode error	Authorization configurado no request header não é base64 válido	Use diretamente o Token obtido, sem qualquer processamento
4001019	Decryption error	Authorization configurado no request header não foi gerado pela EasyAR	Use diretamente o Token obtido, sem qualquer processamento
4001022	API Key's resource is empty	API Key não possui cloud service associado	Verifique se API Key está associada a cloud service e se o cloud service associado expirou
4001024	Token is expired	Token expirou	Gere novamente
4001025	Token generate fail	Falha ao gerar Token	Entre em contato com o suporte técnico: support@easyar.com

Table of Contents

Obter e usar API Key

Criar API Key

Dica

Aviso

Obter Token

Obter Token pelo Developer Center

Nota

Gerar Token com API Key e API Secret

Aviso

Parâmetros de request

Método de signature

Exemplo de signature

Dica

Obter Token

Usar Token

Descrição dos error codes