Obtenir et utiliser API Key

Dans EasyAR Developer Center, le nombre d'API Key pouvant être créées n'est pas limité. Il est recommandé d'attribuer une API Key indépendante à chaque application afin de contrôler les permissions plus finement.

Créer API Key

Connectez-vous à EasyAR Developer Center. Si vous utilisez API Key pour la première fois, créez d'abord une API Key :

Sous "Authorization", cliquez sur "Cloud Service API KEY"
Sur la page "API KEY", cliquez sur "Create API KEY"

APIKey

Renseignez "Application Name"
Cochez les cloud services requis selon les besoins de votre application. Il n'est pas recommandé de tout autoriser.
Cliquez sur "OK"

Astuce

Si vous utilisez SpatialMap, cochez SpatialMap.

Si vous utilisez Cloud Recognition, cochez Cloud Recognition.

Si vous utilisez Mega Landmark, cochez Mega Landmark. Cette fonction nécessite une demande auprès du service commercial avant utilisation.

Si vous utilisez AR Operation Center, cochez AR Operation Center. Cette fonction nécessite une demande auprès du service commercial avant utilisation.

Si vous utilisez Mega Block cloud localization, cochez Mega Block.

APIKey

API Key et API Secret sont alors générés sur la page, comme illustré ci-dessous. Veillez à ne pas les divulguer.

APIKey

Avertissement

N'utilisez pas API Key et API Secret directement dans des applications client comme Web ou WeChat Mini Program.

Obtenir Token

Il existe deux façons d'obtenir Token : 1. directement depuis Developer Center ; 2. par code. Si vous devez contrôler les permissions d'accès aux resources, la deuxième méthode est recommandée. Les deux méthodes sont décrites ci-dessous.

Obtenir Token depuis Developer Center

Sélectionnez une API Key à utiliser, puis cliquez sur "Manage" à droite

APIKeyToken

Choisissez une durée de validité pour le Token
Cliquez sur "Generate Token"
Cliquez sur "Copy"

APIKeyToken

Note

La sécurité est la raison principale de la définition de la durée de validité du Token. Si elle est trop longue, en cas de fuite ou de vol, un attaquant peut l'utiliser longtemps et provoquer fuite de données ou opérations non autorisées. La durée de validité limite la fenêtre d'utilisation du Token ; même divulgué, l'impact reste limité dans le temps.

Générer Token avec API Key et API Secret

La génération de Token exige de signer les paramètres principaux pour assurer la sécurité de la transmission. Ensuite, les données signées sont envoyées au service STS (Security Token Service) pour authentification. Après validation par STS, un access Token temporaire est émis, valable uniquement dans une fenêtre de temps donnée ; après expiration, l'authentification doit être relancée.

Avertissement

Ne générez pas Token dans le client code ; générez-le côté server side puis transmettez-le au client.

Paramètres de request

Nom du champ	Type	Obligatoire	Description
apiKey	string	Oui	API Key
expires	int	Oui	Durée de validité du Token généré, en secondes
acl	string	Oui	Access Control List, contrôle les permissions de resource accessibles au token
timestamp	long	Oui	Timestamp, en millisecondes
signature	string	Oui	Signature

acl : se compose d'un ou plusieurs AC (access control). Chaque AC contient quatre parties : service, effect, resource et permission.

service : type de service ; prend actuellement en charge ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Localization), ecs:vps1 (landmark)
resource : app id du service spécifique, par exemple CRS AppId de la Cloud Recognition library
effect : indique si l'accès correspondant à cette configuration resource peut être exécuté ; valeurs Allow, Deny
permission : valeurs de permission READ, WRITE

Exemple de structure :

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

Méthode de signature

Triez tous les paramètres de request par key name
Pour chaque paramètre, concaténez key name et value en une string
Concaténez toutes les strings obtenues et ajoutez API Secret à la fin
Calculez le sha256 hash de la string ; la valeur hexadécimale est la signature

Exemple de signature

<?php
// votre API Key et votre API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// l App ID de votre service
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// duree de validite, en secondes
$expires = 3600;

// construit les parametres a signer
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// trie
ksort($data);

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

// concatene l API Secret
array_push($builder, $apiSecret);

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

const crypto = require('crypto');

// votre API Key et votre API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// l App ID de votre service
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// duree de validite, en secondes
const expires = 3600

// construit les parametres a signer
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// trie et concatene la chaine
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// concatene l API Secret
builder.push(apiSecret);

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

import time
import hashlib

# votre API Key et votre API Secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# l App ID de votre service
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# duree de validite, en secondes
expires = 3600

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

# concatene la chaine
builder = [f'{key}{value}' for key, value in data.items()]

# concatene l API Secret
builder.append(apiSecret)

# genere la 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 {
        // votre API Key et votre API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // App ID du service
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // duree de validite, en secondes
        int expires = 3600;

        // construit les parametres a signer
        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\"]}]");

        // concatene la chaine
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // concatene l API Secret
        builder.append(apiSecret);

        // genere la 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) {
            // votre API Key et votre API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // App ID du service
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // duree de validite, en secondes
            int expires = 3600;

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

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

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

            // genere la 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() {
    // votre API Key et votre API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // l App ID de votre service
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // duree de validite, en secondes
    expires := 3600

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

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

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

    // concatene l API Secret
    builder.WriteString(apiSecret)

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

Astuce

Lors de l'ajout de la signature, ACL doit être converti en string JSON.

Obtenir Token

Ajoutez la signature générée à la liste des paramètres, puis envoyez la request à l'interface /token/v2 pour obtenir Token.

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

Exemple :

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

Si statusCode vaut 0 dans le résultat retourné, cela indique un succès.

Format de retour 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 pour l'authentification de la business request.
expiration : heure d'expiration du token ; après expiration, il faut redemander un token.

Format de retour d'erreur :

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

Utiliser Token

Dans les request https métier, ajoutez Token au request header au format : {"Authorization": "nuPDCj......xstQX"}.

Lors de l'envoi d'une business API request, le paramètre appId doit être ajouté (consultez le service correspondant dans Developer Center pour sa source).

Description des error codes

Divers errors ou exceptions peuvent survenir lors de la génération et de l'utilisation de Token. Pour aider les developers à localiser rapidement les problèmes et à prendre des mesures efficaces, les error codes courants et leur signification sont détaillés ci-dessous :

Error code	Error message	Description de l'erreur	Solution
4001011	API Key invalid	API Key invalide	Vérifiez si cette API Key existe sous "Cloud Service API KEY"
4001012	Timestamp invalid	Timestamp invalide	L'unité du timestamp est la milliseconde et l'écart avec l'heure standard ne doit pas dépasser 5 minutes
4001015	Signature invalid	Signature invalide	Vérifiez si l'algorithme de signature est correct et si API Secret correspond à API KEY
4001017	AppId is not authorized by this API Key	API Key n'a pas autorisé cet AppId	Vérifiez si le service auquel appartient AppId est associé à cette API Key
4001018	Base64 decode error	Authorization défini dans le request header n'est pas un base64 valide	Utilisez directement le Token obtenu sans aucun traitement
4001019	Decryption error	Authorization défini dans le request header n'a pas été généré par EasyAR	Utilisez directement le Token obtenu sans aucun traitement
4001022	API Key's resource is empty	API Key n'a pas de cloud service associé	Vérifiez si API Key est associée à un cloud service et si celui-ci a expiré
4001024	Token is expired	Token a expiré	Regénérez-le
4001025	Token generate fail	Échec de génération du Token	Contactez le support technique : support@easyar.com

Table of Contents

Obtenir et utiliser API Key

Créer API Key

Astuce

Avertissement

Obtenir Token

Obtenir Token depuis Developer Center

Note

Générer Token avec API Key et API Secret

Avertissement

Paramètres de request

Méthode de signature

Exemple de signature

Astuce

Obtenir Token

Utiliser Token

Description des error codes