Api key 가져오기 및 사용하기

EasyAR 개발 센터에서 API Key 생성은 수량 제한이 없으며, 다른 애플리케이션마다 독립적인 API Key를 할당하여 권한을 세밀하게 관리할 것을 권장합니다.

Api key 생성

EasyAR 개발 센터에 로그인하세요. API Key를 처음 사용하는 경우, 다음 단계에 따라 API Key를 생성하세요:

"권한" 아래에서 "클라우드 서비스 API KEY" 클릭
"API KEY" 페이지에서 "API KEY 생성" 버튼 클릭

APIKey

"애플리케이션 이름" 입력
애플리케이션 요구 사항에 따라 필요한 클라우드 서비스를 선택하세요. 전체 권한 부여는 권장하지 않습니다.
"확인" 클릭

팁

SpatialMap 사용 시 SpatialMap 선택.

클라우드 인식 사용 시 클라우드 인식 선택.

Mega Landmark 사용 시 Mega Landmark 선택. 이 기능 사용 전 비즈니스팀에 문의 필요.

AR 운영 센터 사용 시 AR 운영 센터 선택. 이 기능 사용 전 비즈니스팀에 문의 필요.

Mega Block 클라우드 포지셔닝 사용 시 Mega Block 선택.

APIKey

페이지에 API Key와 API Secret이 생성됩니다. 아래 그림과 같이 유출되지 않도록 주의하세요.

APIKey

경고

클라이언트(예: Web, 위챗 미니프로그램 등) 애플리케이션에서 직접 API Key와 API Secret을 사용하지 마세요.

Token 획득

Token을 획득하는 방법은 두 가지입니다: 1. 개발 센터에서 직접 획득; 2. 코드 작성으로 획득. 리소스 접근 권한 제어가 필요한 경우 두 번째 방법을 권장합니다. 아래에서 각 방법을 설명하니 요구 사항에 따라 선택하세요.

개발 센터에서 Token 획득

사용할 API Key를 선택하고 오른쪽의 "관리" 클릭

APIKeyToken

Token의 유효 기간 선택
"Token 생성" 클릭
"복사" 클릭

APIKeyToken

참고

‌보안은 Token 유효 기간 설정의 주요 이유입니다.‌ Token 유효 기간이 너무 길면 유출되거나 탈취될 경우 공격자가 장기간 사용하여 데이터 유출 또는 무단 작업을 초래할 수 있습니다. 유효 기간은 Token의 유효 기간을 제한하여 유출되더라도 단기간 내에만 피해가 제한되도록 합니다.

Api key와 api secret을 사용하여 token 생성

Token 생성 과정은 핵심 매개변수에 대한 서명 작업을 요구하며 전송 보안을 보장합니다. 그런 다음 서명된 데이터는 STS(Security Token Service) 서비스로 전송되어 인증을 받습니다. STS 서비스가 검증을 통과하면 지정된 시간 동안만 유효한 임시 접근 Token을 발급하며, 시간 초과 후에는 재인증을 요청해야 합니다.

경고

클라이언트 코드에서 Token을 생성하지 말고, 서버 측에서 Token을 생성한 후 클라이언트에 전달하여 사용하세요.

요청 매개변수

필드명	타입	필수 여부	설명
apiKey	string	예	API Key
expires	int	예	생성된 토큰 유효 시간 (단위: 초)
acl	string	예	접근 제어 목록 (Access Control List), 토큰의 리소스 접근 권한 제어
timestamp	long	예	타임스탬프 (단위: 밀리초)
signature	string	예	서명

acl: 하나 이상의 AC(접근 제어)로 구성되며, 각 AC는 service, effect, resource, permission 네 부분을 포함합니다.

service: 서비스 유형. 현재 지원: ecs:crs(클라우드 인식), ecs:spatialmap(희소 공간 맵), ecs:cls(Mega Block 클라우드 위치 추적), ecs:vps1(랜드마크)
resource: 특정 서비스의 app id. 예: 클라우드 인식 라이브러리의 CRS AppId
effect: 해당 resource 설정 항목과 일치하는 접근의 실행 허용 여부 지정. 값: Allow, Deny
permission: 권한 값. READ, WRITE

구조 예시:

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

서명 방법

모든 요청 매개변수를 키 이름 기준으로 정렬
각 매개변수에 대해 키 이름과 값을 문자열로 결합
생성된 모든 문자열을 결합하고 마지막에 API Secret 추가
문자열의 sha256 해시를 계산한 16진수 값이 서명입니다.

서명 예제

<?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)
}

팁

서명 생성 시 ACL을 JSON 문자열로 변환해야 합니다.

Token 획득

생성된 서명을 매개변수 목록에 추가하고 /token/v2 엔드포인트로 요청을 전송하여 Token을 획득합니다.

요청 주소: https://uac.easyar.com/token/v2 또는 https://uac-na1.easyar.com/token/v2 (북미 1)
요청 방식: POST
요청 헤더: Content-Type: application/json
요청 매개변수: {"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"}'

Return results if statusCode is 0, it indicates success.

정상 응답 형식:

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

token: 비즈니스 요청 인증을 위한 토큰.
expiration: 토큰 만료 시간, 만료 후에는 토큰을 재발급 받아야 함.

오류 응답 형식:

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

Token 사용

비즈니스 https 요청 시 Token을 요청 헤더에 추가합니다. 형식: {"Authorization": "nuPDCj......xstQX"}.

비즈니스 API 요청 전송 시 appId 매개변수를 추가해야 합니다(출처는 개발 센터에서 관련 서비스 확인).

오류 코드 설명

Token 생성 및 사용 과정에서 다양한 오류나 예외 상황이 발생할 수 있습니다. 개발자가 문제를 신속하게 진단하고 효과적인 해결책을 마련할 수 있도록 일반적인 오류 코드와 그 의미를 상세히 설명합니다:

오류 코드	오류 메시지	오류 설명	해결 방법
4001011	Api key invalid	API Key가 유효하지 않음	"클라우드 서비스 API KEY"에서 해당 API Key가 있는지 확인
4001012	Timestamp invalid	타임스탬프가 유효하지 않음	타임스탬프 단위는 밀리초이며 표준 시간과 오차가 5분을 초과하지 않아야 함
4001015	Signature invalid	서명이 유효하지 않음	서명 알고리즘이 올바른지 확인 및 API Secret과 API KEY가 일치하는지 확인
4001017	AppId is not authorized by this api key	API Key가 이 AppId를 인증받지 않음	AppId가 속한 서비스가 이 API Key와 연결되었는지 확인
4001018	Base64 decode error	요청 헤더에 설정된 Authorization이 유효한 base64 형식이 아님	획득한 Token을 변경 없이 직접 사용
4001019	Decryption error	요청 헤더에 설정된 Authorization이 EasyAR에서 생성된 것이 아님	획득한 Token을 변경 없이 직접 사용
4001022	Api key's resource is empty	API Key에 연결된 클라우드 서비스가 없음	API Key가 클라우드 서비스와 연결되었는지 및 연결된 서비스의 만료 여부 확인
4001024	Token is expired	Token이 만료됨	재생성
4001025	Token generate fail	Token 생성 실패	기술 지원팀에 문의: support@easyar.com

Table of Contents

Api key 가져오기 및 사용하기

Api key 생성

팁

경고

Token 획득

개발 센터에서 Token 획득

참고

Api key와 api secret을 사용하여 token 생성

경고

요청 매개변수

서명 방법

서명 예제

팁

Token 획득

Token 사용

오류 코드 설명