API Key 가져오기 및 사용

EasyAR Developer Center에서 생성할 수 있는 API Key 수에는 제한이 없습니다. permission을 더 세밀하게 관리할 수 있도록 애플리케이션별로 독립적인 API Key를 할당하는 것이 좋습니다.

API Key 생성

EasyAR Developer Center에 로그인합니다. API Key를 처음 사용하는 경우 먼저 다음 단계로 API Key를 생성하십시오.

"Authorization" 아래에서 "Cloud Service API KEY" 클릭
"API KEY" 페이지에서 "Create API KEY" 버튼 클릭

APIKey

"Application Name" 입력
애플리케이션 요구에 따라 필요한 cloud service를 선택합니다. 모두 권한 부여하는 것은 권장하지 않습니다.
"OK" 클릭

팁

SpatialMap을 사용하는 경우 SpatialMap을 선택합니다.

Cloud Recognition을 사용하는 경우 Cloud Recognition을 선택합니다.

Mega Landmark를 사용하는 경우 Mega Landmark를 선택합니다. 이 기능은 사용 전 영업 담당자에게 신청해야 합니다.

AR Operation Center를 사용하는 경우 AR Operation Center를 선택합니다. 이 기능은 사용 전 영업 담당자에게 신청해야 합니다.

Mega Block cloud localization을 사용하는 경우 Mega Block을 선택합니다.

APIKey

이때 아래 그림처럼 페이지에 API Key와 API Secret이 생성됩니다. 유출되지 않도록 주의하십시오.

APIKey

경고

Web, WeChat Mini Program 등의 client 애플리케이션에서 API Key와 API Secret을 직접 사용하지 마십시오.

Token 가져오기

Token을 얻는 방법은 두 가지입니다. 1. Developer Center에서 직접 가져오기, 2. 코드를 작성하여 가져오기. resource 접근 permission 제어가 필요하다면 두 번째 방법을 권장합니다. 아래에서 두 방법을 각각 설명합니다.

Developer Center에서 Token 가져오기

사용할 API Key를 선택하고 오른쪽의 "Manage"를 클릭합니다

APIKeyToken

Token 유효 기간 선택
"Generate Token" 클릭
"Copy" 클릭

APIKeyToken

참고

보안은 Token 유효 기간 설정의 가장 중요한 이유입니다. Token 유효 기간이 너무 길면 유출 또는 도난 시 공격자가 장기간 사용할 수 있어 데이터 유출이나 무단 작업으로 이어질 수 있습니다. 유효 기간은 Token의 유효 창을 제한하므로 유출되어도 피해가 짧은 시간으로 제한됩니다.

API Key와 API Secret으로 Token 생성

Token 생성 과정에서는 전송 보안을 보장하기 위해 핵심 파라미터에 signature 작업이 필요합니다. 이후 서명된 데이터는 STS(Security Token Service) 서비스로 전송되어 인증됩니다. STS 검증이 통과되면 지정된 시간 창에서만 유효한 임시 access Token이 발급되며, 만료 후에는 인증 과정을 다시 시작해야 합니다.

경고

client code에서 Token을 생성하지 말고 server side에서 생성한 뒤 client에 전달하여 사용하십시오.

Request 파라미터

필드 이름	타입	필수 여부	설명
apiKey	string	예	API Key
expires	int	예	생성된 Token의 유효 시간, 단위는 초
acl	string	예	Access Control List, token이 접근할 수 있는 resource 권한 제어
timestamp	long	예	Timestamp, 단위는 밀리초
signature	string	예	Signature

acl: 하나 이상의 AC(access control)로 구성됩니다. 각 AC는 service, effect, resource, permission 네 부분을 포함합니다.

service: 서비스 유형. 현재 ecs:crs(Cloud Recognition), ecs:spatialmap(Sparse Spatial Map), ecs:cls(Mega Block Cloud Localization), ecs:vps1(landmark)을 지원합니다
resource: 특정 서비스의 app id, 예: Cloud Recognition library의 CRS AppId
effect: 이 resource 구성 항목과 일치하는 접근을 실행할 수 있는지 지정합니다. 값은 Allow, Deny
permission: 권한 값 READ, WRITE

구조 예:

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

Signature 방법

request의 모든 파라미터를 key name 기준으로 정렬합니다
각 파라미터에 대해 key name과 value를 이어 string으로 만듭니다
이렇게 얻은 모든 string을 이어 붙이고 마지막에 API Secret을 붙입니다
string의 sha256 hash를 계산한 16진수 값이 signature입니다

Signature 예제

<?php
// 사용자의 API Key 및 API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// 사용자 서비스의 App ID
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// 유효 시간, 단위는 초
$expires = 3600;

// 서명할 매개변수 구성
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// 정렬
ksort($data);

// 문자열 연결
$builder = [];
foreach ($data as $key => $value) {
    array_push($builder, $key . $value);
}

// API Secret 연결
array_push($builder, $apiSecret);

// 서명 생성
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// 사용자의 API Key 및 API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// 사용자 서비스의 App ID
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// 유효 시간, 단위는 초
const expires = 3600

// 서명할 매개변수 구성
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// 문자열 정렬 및 연결
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// API Secret 연결
builder.push(apiSecret);

// 서명 생성
const signature = crypto.createHash('sha256').update(builder.join('')).digest('hex');
console.info(signature);

import time
import hashlib

# 사용자의 API Key 및 API Secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# 사용자 서비스의 App ID
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# 유효 시간, 단위는 초
expires = 3600

# 서명할 매개변수 구성
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

# 문자열 연결
builder = [f'{key}{value}' for key, value in data.items()]

# API Secret 연결
builder.append(apiSecret)

# 서명 생성
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 및 API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // 서비스의 App ID
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // 유효 시간, 단위는 초
        int expires = 3600;

        // 서명할 매개변수 구성
        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\"]}]");

        // 문자열 연결
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // API Secret 연결
        builder.append(apiSecret);

        // 서명 생성
        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 및 API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // 서비스의 App ID
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // 유효 시간, 단위는 초
            int expires = 3600;

            // 서명할 매개변수 구성
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

            // 문자열 연결
            StringBuilder builder = new StringBuilder();
            data.ToList().ForEach(pair => builder.Append($"{pair.Key}{pair.Value}"));

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

            // 서명 생성
            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 및 API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // 사용자 서비스의 App ID
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // 유효 시간, 단위는 초
    expires := 3600

    // 서명할 매개변수 구성
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

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

    // API Secret 연결
    builder.WriteString(apiSecret)

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

팁

signature를 추가할 때 ACL은 JSON string으로 변환해야 합니다.

Token 가져오기

위에서 생성한 signature를 파라미터 목록에 추가하고 /token/v2 interface로 request를 보내 Token을 가져옵니다.

request 주소: https://uac.easyar.com/token/v2 또는 https://uac-na1.easyar.com/token/v2 (North America 1)
request 방식: POST
request header: Content-Type: application/json
request 매개변수:{"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

예시는 다음과 같습니다.

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

반환 결과의 statusCode가 0이면 성공을 의미합니다.

정상 반환 형식:

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

token: business request 인증용 Token.
expiration: token 만료 시간. 만료 후에는 token을 다시 신청해야 합니다.

오류 반환 형식:

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

Token 사용

business https request에서 Token을 request header에 추가합니다. 형식: {"Authorization": "nuPDCj......xstQX"}.

business API request를 보낼 때 appId 파라미터를 추가해야 합니다(출처는 Developer Center의 관련 service에서 확인).

Error code 설명

Token 생성 및 Token 사용 과정에서 여러 error 또는 exception이 발생할 수 있습니다. developer가 문제를 빠르게 찾고 효과적인 해결 조치를 취할 수 있도록, 일반적인 error code와 의미를 아래에 설명합니다.

Error code	Error message	Error 설명	해결 방법
4001011	API Key invalid	API Key가 유효하지 않음	"Cloud Service API KEY" 아래에 이 API Key가 있는지 확인
4001012	Timestamp invalid	Timestamp가 유효하지 않음	timestamp 단위는 밀리초이며 표준 시간과의 오차가 5분을 넘지 않아야 함
4001015	Signature invalid	Signature가 유효하지 않음	signature algorithm이 올바른지, API Secret과 API KEY가 일치하는지 확인
4001017	AppId is not authorized by this API Key	API Key가 이 AppId를 승인하지 않음	AppId가 속한 service가 이 API Key에 연결되어 있는지 확인
4001018	Base64 decode error	request header에 설정한 Authorization이 유효한 base64 형식이 아님	얻은 Token을 아무 처리 없이 직접 사용
4001019	Decryption error	request header에 설정한 Authorization이 EasyAR에서 생성한 것이 아님	얻은 Token을 아무 처리 없이 직접 사용
4001022	API Key's resource is empty	API Key에 연결된 cloud service가 없음	API Key가 cloud service에 연결되어 있는지, 연결된 cloud service가 만료되었는지 확인
4001024	Token is expired	Token이 만료됨	다시 생성
4001025	Token generate fail	Token 생성 실패	기술 지원에 문의: support@easyar.com

Table of Contents

API Key 가져오기 및 사용

API Key 생성

팁

경고

Token 가져오기

Developer Center에서 Token 가져오기

참고

API Key와 API Secret으로 Token 생성

경고

Request 파라미터

Signature 방법

Signature 예제

팁

Token 가져오기

Token 사용

Error code 설명