Mendapatkan dan menggunakan API Key

Tidak ada batas jumlah API Key yang dapat dibuat di EasyAR Developer Center. Disarankan membuat API Key terpisah untuk aplikasi yang berbeda agar permission dapat dikontrol lebih rinci.

Membuat API Key

Login ke EasyAR Developer Center. Jika ini pertama kali Anda menggunakan API Key, buat API Key terlebih dahulu dengan langkah berikut:

Di bawah "Authorization", klik "Cloud Service API KEY"
Pada halaman "API KEY", klik tombol "Create API KEY"

APIKey

Isi "Application Name"
Pilih cloud service yang diperlukan sesuai kebutuhan aplikasi Anda. Tidak disarankan memberi semua permission.
Klik "OK"

Kiat

Jika menggunakan SpatialMap, pilih SpatialMap.

Jika menggunakan Cloud Recognition, pilih Cloud Recognition.

Jika menggunakan Mega Landmark, pilih Mega Landmark. Fitur ini memerlukan pengajuan ke sales sebelum digunakan.

Jika menggunakan AR Operation Center, pilih AR Operation Center. Fitur ini memerlukan pengajuan ke sales sebelum digunakan.

Jika menggunakan Mega Block cloud localization, pilih Mega Block.

APIKey

Pada saat ini API Key dan API Secret akan dibuat di halaman seperti gambar berikut. Jangan membocorkannya.

APIKey

Peringatan

Jangan gunakan API Key dan API Secret secara langsung pada aplikasi client seperti Web atau WeChat Mini Program.

Mendapatkan Token

Ada dua cara untuk mendapatkan Token: 1. mendapatkannya langsung dari Developer Center; 2. mendapatkannya dengan menulis kode. Jika Anda perlu mengontrol permission akses resource, disarankan menggunakan cara kedua. Dua cara ini dijelaskan di bawah; pilih sesuai kebutuhan Anda.

Mendapatkan Token dari Developer Center

Pilih API Key yang ingin digunakan, lalu klik "Manage" di sisi kanan

APIKeyToken

Pilih masa berlaku Token
Klik "Generate Token"
Klik "Copy"

APIKeyToken

Catatan

Keamanan adalah alasan utama pengaturan masa berlaku Token. Jika masa berlaku Token terlalu panjang, setelah bocor atau dicuri, penyerang dapat menggunakannya dalam jangka panjang sehingga menyebabkan kebocoran data atau operasi tidak sah. Masa berlaku membatasi jendela valid Token; meskipun bocor, dampaknya hanya berlangsung singkat.

Menghasilkan Token menggunakan API Key dan API Secret

Proses pembuatan Token mengharuskan parameter inti ditandatangani untuk memastikan keamanan transmisi. Setelah itu, data yang telah ditandatangani dikirim ke layanan STS (Security Token Service) untuk autentikasi identitas. Setelah layanan STS memverifikasi, layanan akan menerbitkan Token akses sementara yang hanya valid dalam jendela waktu tertentu; setelah kedaluwarsa, proses autentikasi harus dijalankan kembali.

Peringatan

Jangan menghasilkan Token di kode client. Hasilkan Token di sisi server, lalu kirimkan ke client untuk digunakan.

Parameter request

Nama field	Tipe	Wajib	Deskripsi
apiKey	string	Ya	API Key
expires	int	Ya	Masa berlaku Token yang dibuat, dalam detik
acl	string	Ya	Access Control List, mengontrol izin resource yang dapat diakses token
timestamp	long	Ya	Timestamp, dalam milidetik
signature	string	Ya	Signature

acl: terdiri dari satu atau beberapa AC (access control). Setiap AC berisi empat bagian: service, effect, resource, dan permission.

service: tipe layanan; saat ini mendukung ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Localization), ecs:vps1 (landmark)
resource: app id layanan tertentu, misalnya CRS AppId dari Cloud Recognition library
effect: menentukan apakah akses yang cocok dengan konfigurasi resource ini dapat dijalankan; nilainya Allow atau Deny
permission: nilai izin READ, WRITE

Contoh struktur:

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

Metode signature

Urutkan semua parameter request berdasarkan nama key
Untuk setiap parameter, gabungkan nama key dan value menjadi string
Gabungkan semua string tersebut, lalu tambahkan API Secret di akhir
Hitung hash sha256 string dan gunakan nilai heksadesimalnya sebagai signature

Contoh signature

<?php
// API Key dan API Secret Anda
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// App ID layanan Anda
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// waktu berlaku, dalam detik
$expires = 3600;

// buat parameter yang akan ditandatangani
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// urutkan
ksort($data);

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

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

// hasilkan tanda tangan
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// API Key dan API Secret Anda
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// App ID layanan Anda
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// waktu berlaku, dalam detik
const expires = 3600

// buat parameter yang akan ditandatangani
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// urutkan dan gabungkan string
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

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

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

import time
import hashlib

# API Key dan API Secret Anda
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# App ID layanan Anda
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# waktu berlaku, dalam detik
expires = 3600

# buat parameter yang akan ditandatangani
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

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

# gabungkan API Secret
builder.append(apiSecret)

# hasilkan tanda tangan
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 {
        // API Key dan API Secret Anda
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // App ID layanan
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // waktu berlaku, dalam detik
        int expires = 3600;

        // buat parameter yang akan ditandatangani
        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\"]}]");

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

        // gabungkan API Secret
        builder.append(apiSecret);

        // hasilkan tanda tangan
        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) {
            // API Key dan API Secret Anda
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // App ID layanan
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // waktu berlaku, dalam detik
            int expires = 3600;

            // buat parameter yang akan ditandatangani
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

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

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

            // hasilkan tanda tangan
            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() {
    // API Key dan API Secret Anda
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // App ID layanan Anda
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // waktu berlaku, dalam detik
    expires := 3600

    // buat parameter yang akan ditandatangani
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

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

    // gabungkan API Secret
    builder.WriteString(apiSecret)

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

Kiat

Saat menambahkan signature, ACL perlu dikonversi menjadi string JSON.

Mendapatkan Token

Tambahkan signature yang telah dibuat ke daftar parameter, lalu kirim request ke interface /token/v2 untuk mendapatkan Token.

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

Contohnya sebagai berikut:

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

Jika statusCode dalam hasil return adalah 0, berarti berhasil.

Format return 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 untuk autentikasi request bisnis.
expiration: waktu kedaluwarsa token; setelah kedaluwarsa, token perlu diajukan ulang.

Format return error:

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

Menggunakan Token

Dalam request https bisnis, tambahkan Token ke request header dengan format: {"Authorization": "nuPDCj......xstQX"}.

Saat mengirim request API bisnis, parameter appId perlu ditambahkan (lihat layanan terkait di Developer Center untuk asal nilainya).

Penjelasan error code

Berbagai error atau exception dapat terjadi selama pembuatan dan penggunaan Token. Untuk membantu developer menemukan masalah dengan cepat dan mengambil tindakan yang efektif, berikut penjelasan detail error code umum dan artinya:

Error code	Error message	Penjelasan error	Solusi
4001011	API Key invalid	API Key tidak valid	Periksa apakah API Key ini ada di bawah "Cloud Service API KEY"
4001012	Timestamp invalid	Timestamp tidak valid	Satuan timestamp adalah milidetik, dan selisih dari waktu standar tidak boleh melebihi 5 menit
4001015	Signature invalid	Signature tidak valid	Periksa apakah algoritma signature benar, dan apakah API Secret cocok dengan API KEY
4001017	AppId is not authorized by this API Key	API Key belum memberi otorisasi untuk AppId ini	Periksa apakah layanan tempat AppId berada dikaitkan dengan API Key ini
4001018	Base64 decode error	Authorization yang diatur di request header bukan format base64 yang valid	Gunakan Token yang diperoleh secara langsung tanpa pemrosesan apa pun
4001019	Decryption error	Authorization yang diatur di request header bukan hasil dari EasyAR	Gunakan Token yang diperoleh secara langsung tanpa pemrosesan apa pun
4001022	API Key's resource is empty	API Key tidak memiliki cloud service terkait	Periksa apakah API Key dikaitkan dengan cloud service dan apakah cloud service terkait sudah kedaluwarsa
4001024	Token is expired	Token sudah kedaluwarsa	Buat ulang
4001025	Token generate fail	Pembuatan Token gagal	Hubungi dukungan teknis: support@easyar.com

Table of Contents

Mendapatkan dan menggunakan API Key

Membuat API Key

Kiat

Peringatan

Mendapatkan Token

Mendapatkan Token dari Developer Center

Catatan

Menghasilkan Token menggunakan API Key dan API Secret

Peringatan

Parameter request

Metode signature

Contoh signature

Kiat

Mendapatkan Token

Menggunakan Token

Penjelasan error code