인증

aicon API의 인증 방식을 설명합니다.

Basic Auth 인증

모든 API 요청은 HTTP Basic 인증으로 인증합니다. Basic 인증은 username:password 쌍을 Base64로 인코딩하여 Authorization 헤더에 담는 방식입니다.

aicon API에서는 Secret Key가 username, 비밀번호는 사용하지 않습니다. 비밀번호가 없더라도 username과 password를 구분하는 :(콜론)은 반드시 포함해야 합니다.

Authorization: Basic {base64(secretKey:)}

인코딩 과정

Secret Key가 test_sk_abcdef123456인 경우, 다음 단계를 거칩니다.

1단계 — Secret Key 뒤에 :를 붙입니다.

test_sk_abcdef123456:

콜론을 빠트리지 마세요

:는 Basic 인증에서 username과 password의 구분자입니다. 비밀번호가 비어 있어도 콜론은 반드시 포함해야 합니다. 콜론이 없으면 인증에 실패합니다.

입력	결과
`test_sk_abcdef123456:`	인증 성공
`test_sk_abcdef123456`	인증 실패 — 콜론 누락

2단계 — Base64로 인코딩합니다.

터미널에서 아래 명령어로 직접 확인할 수 있습니다.

echo -n "test_sk_abcdef123456:" | base64
# dGVzdF9za19hYmNkZWYxMjM0NTY6

UTF-8 BOM 주의

일부 환경에서 문자열에 UTF-8 BOM이 포함되면 Base64 결과가 77u/로 시작할 수 있습니다. 이 경우 인증에 실패하므로 BOM이 없는 UTF-8로 인코딩해야 합니다.

3단계 — Authorization 헤더에 담아 요청합니다.

Authorization: Basic dGVzdF9za19hYmNkZWYxMjM0NTY6

언어별 예시

cURL
Node.js
Python

# -u 옵션은 자동으로 Base64 인코딩합니다.
# 시크릿 키 뒤에 반드시 콜론(:)을 포함하세요.
curl -u "test_sk_abcdef123456:" \
  https://api.aiconbiz.kr/v1/coupons

직접 헤더를 설정할 수도 있습니다.

curl -X GET https://api.aiconbiz.kr/v1/coupons \
  -H "Authorization: Basic dGVzdF9za19hYmNkZWYxMjM0NTY6"

const secretKey = 'test_sk_abcdef123456';
// 시크릿 키 뒤에 반드시 콜론(:)을 포함하세요.
const encoded = Buffer.from(`${secretKey}:`).toString('base64');

const response = await fetch('https://api.aiconbiz.kr/v1/coupons', {
  headers: {
    'Authorization': `Basic ${encoded}`,
  },
});

import base64
import requests

secret_key = "test_sk_abcdef123456"
# 시크릿 키 뒤에 반드시 콜론(:)을 포함하세요.
encoded = base64.b64encode(f"{secret_key}:".encode()).decode()

response = requests.get(
    "https://api.aiconbiz.kr/v1/coupons",
    headers={"Authorization": f"Basic {encoded}"},
)

시크릿 키를 외부에 노출하지 마세요

시크릿 키는 서버에서만 사용하세요. 브라우저 JavaScript, 앱 클라이언트 코드, 공개 저장소 등에 시크릿 키가 포함되면 보안 사고로 이어질 수 있습니다. 키가 노출된 경우 즉시 aicon 콘솔에서 키를 재발급하세요.

인증 실패 응답

인증에 실패하면 401 응답이 반환됩니다.

{
  "status": 401,
  "code": "AUTH_INVALID_API_KEY",
  "message": "유효하지 않은 API 키입니다."
}

조직 상태로 인한 거절

키는 정상인데 조직이 이용 가능한 상태가 아니면 403 이 반환됩니다.

{
  "status": 403,
  "code": "AUTH_ORGANIZATION_NOT_ACTIVE",
  "message": "이용할 수 없는 조직입니다. 담당자에게 문의해 주세요."
}

401 과 구분해서 처리하세요. 이 응답은 키 문제가 아니므로 키를 재발급해도 같은 결과가 나옵니다. 재시도로도 풀리지 않습니다.

가입 심사가 끝나지 않았거나, 조직 이용이 정지된 경우에 발생합니다
콘솔의 설정 > 일반 화면에서 현재 상태와 남은 절차를 확인할 수 있습니다
해결되지 않으면 담당자에게 문의하세요

연동 시 권장 처리

이 코드를 받으면 재시도 없이 즉시 알림을 띄우고 요청을 멈추세요. 자동 재시도 루프에 넣으면 상태가 풀릴 때까지 같은 요청이 계속 쌓입니다.

허용 IP로 인한 거절

키에 허용 IP 제한을 켜 두었는데 목록에 없는 IP에서 호출하면 403 이 반환됩니다. detail.ip 에는 aicon이 본 호출 IP가 담깁니다.

{
  "status": 403,
  "code": "AUTH_IP_NOT_ALLOWED",
  "message": "이 API 키에 허용되지 않은 IP에서 호출했습니다. 콘솔에서 이 키의 허용 IP를 확인해 주세요.",
  "detail": {
    "ip": "203.0.113.25"
  }
}

허용 IP는 고객사가 콘솔의 API > 키 관리에서 키마다(테스트·라이브 따로) IP 관리 버튼으로 정합니다. 이 응답을 받으면 다음을 확인하세요.

detail.ip 가 호출한 서버의 IP가 맞다면 그 IP를 허용 IP에 추가하세요
detail.ip 는 aicon이 받은 공인(외부) IP입니다. NAT·프록시 뒤에서 호출한다면 서버 내부 IP가 아니라 나가는 쪽 IP를 등록해야 합니다
알지 못하는 IP라면 키가 유출됐을 수 있습니다. 키를 재발급하세요 — 허용 IP 설정은 새 키로 그대로 이어집니다

이 응답도 키 문제가 아니므로 키를 재발급해도 같은 결과가 나옵니다.

설정은 최대 5분 뒤에 반영됩니다

aicon API 서버는 키 인증 결과를 최대 5분 동안 저장(캐시)해 둡니다. 허용 IP를 켜거나 끄고, IP를 추가·삭제한 결과는 최대 5분 뒤 적용되며, 그동안은 이전 설정대로 처리될 수 있습니다. IP를 추가한 직후에도 이 코드가 나오면 잠시 뒤 다시 시도하세요.

Basic Auth 인증​

인코딩 과정​

언어별 예시​

인증 실패 응답​

조직 상태로 인한 거절​

허용 IP로 인한 거절​