REST API v2

인증 (v2)

개요

v2 API는 서명 기반의 Bearer 토큰 방식을 사용합니다. 토큰은 sgv2.{payload}.{signature} 형태이며, 발급 후 24시간 동안 유효합니다.

⚠️ v1 토큰과 v2 토큰은 호환되지 않습니다. v2 엔드포인트에는 반드시 v2 토큰을 사용해야 합니다.

토큰 발급 API

Request

POST /api/v2/token

Headers

Authorization 설정 방법

1. 엑세스 키와 시크릿 키를 :로 연결

   ACCESS_KEY:SECRET_KEY
   

2. 해당 문자열을 Base64 인코딩

3. 헤더에 다음 형태로 설정

   Authorization: Basic {인코딩된 값}
   

💡 Tip: 로그인 > 연동하기 > 앱 · API 연동 > 내 앱 · API 키에서 앱을 등록하세요. 신규 앱은 기본으로 자동 승인되어 액세스 키와 시크릿 키를 바로 사용할 수 있습니다. 문제가 발견된 앱은 사용이 중지되며, 기존 토큰도 차단됩니다. 발신번호·기업·템플릿 등의 별도 승인 요건은 그대로 적용됩니다.

Response

성공 응답

{
  "message": "Success",
  "data": {
    "token": "sgv2.eyJ2ZXJzaW9uIjoidjIiLCJhcHBsaWNhdGlvbl9pZCI6IjEiLCJub25jZSI6ImFiY2QiLCJpc3N1ZWRfYXQiOjE3MDA4MDAwMDB9.abc123signature",
    "expires_at": "2024-09-05T07:28:21.000000Z"
  },
  "meta": {
    "version": "v2"
  }
}

API 호출 시 인증 헤더

토큰 발급 후 모든 v2 API 요청에 아래 헤더를 포함해야 합니다.

Authorization: Bearer {발급받은_v2_토큰}

예시

GET /api/v2/credits HTTP/1.1
Authorization: Bearer sgv2.eyJ2ZXJzaW9uIjoidjIifQ.abc123signature
Content-Type: application/json

v2 응답 형식

토큰 발급 API는 message, data, meta 구조를 사용합니다. 토큰 인증이 필요한 v2 API는 traceId, message, data 구조를 사용하며, 문제 발생 시 traceId로 로그를 추적할 수 있습니다.

성공 응답

{
  "traceId": "01J2XXXXXXXXXXXXXXXXXXXXX",
  "message": "Success",
  "data": { }
}

실패 응답

{
  "traceId": "01J2XXXXXXXXXXXXXXXXXXXXX",
  "code": "TOKEN_EXPIRED",
  "message": "Expired Token",
  "errors": [],
  "timestamp": "2024-09-04 07:28:21"
}

주요 에러 코드

예제 코드

<?php
// 1. v2 토큰 발급
$baseUrl = 'https://your-domain.com';
$accessKey = 'access_key';
$secretKey = 'secret_key';

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "{$baseUrl}/api/v2/token",
    CURLOPT_HTTPHEADER => [
        'Authorization: Basic ' . base64_encode($accessKey . ':' . $secretKey),
        'Content-Type: application/x-www-form-urlencoded',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
]);
$response = json_decode(curl_exec($curl), true);
curl_close($curl);

$v2Token = $response['data']['token']; // sgv2.xxx.xxx

// 2. v2 토큰으로 API 호출
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "{$baseUrl}/api/v2/credits",
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $v2Token,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = curl_exec($curl);
curl_close($curl);

echo $result;

const baseUrl = 'https://your-domain.com';
const accessKey = 'access_key';
const secretKey = 'secret_key';

// 1. v2 토큰 발급
const tokenRes = await fetch(`${baseUrl}/api/v2/token`, {
    method: 'POST',
    headers: {
        'Authorization': 'Basic ' + btoa(`${accessKey}:${secretKey}`),
        'Content-Type': 'application/x-www-form-urlencoded',
    },
});
const { data } = await tokenRes.json();
const v2Token = data.token; // sgv2.xxx.xxx

// 2. v2 토큰으로 API 호출
const res = await fetch(`${baseUrl}/api/v2/credits`, {
    headers: {
        'Authorization': `Bearer ${v2Token}`,
        'Content-Type': 'application/json',
    },
});
console.log(await res.json());

주의사항

• v2 토큰은 발급 후 24시간 동안 유효합니다.
• 토큰 재발급 시 이전 v2 토큰은 즉시 무효화됩니다.
• v2 토큰은 반드시 sgv2. 로 시작해야 하며, 그렇지 않으면 INVALID_BEARER_TOKEN_PREFIX 오류가 반환됩니다.
• v1 엔드포인트(/api/v1/...)에는 v1 토큰을, v2 엔드포인트(/api/v2/...)에는 v2 토큰을 사용해야 합니다.