API 키 발급과 인증: x-api-key, /auth-check, AU017

KAT Cloud API 인증은 콘솔에서 발급한 API 키 전체 문자열을 모든 요청의 x-api-key 헤더에 넣는 방식입니다. 키가 유효한지는 GET /auth-check로 확인하고, 응답의 groupIdList로 이 키에 연결된 그룹을 알 수 있습니다. 문자 발신 API는 모든 사용자가 쓸 수 있지만, 그 밖의 API는 비즈니스 요금제 그룹 또는 별도 허용된 그룹에서만 동작하며 조건을 못 채우면 403 AU017이 반환됩니다.

x-api-key 헤더로 인증하는 방식

KAT Cloud(캣클라우드) API의 기본 규칙은 다음과 같습니다.

API 키는 KAT Cloud 콘솔에서 발급하며 사용자 단위로 만들어집니다. 발급받은 키 문자열 전체를 헤더 값으로 그대로 넣습니다. Authorization 헤더나 Bearer 접두어는 쓰지 않습니다. 아래 예제는 모두 키를 환경 변수 KAT_API_KEY에서 읽습니다.

export KAT_API_KEY="콘솔에서 발급받은 키 전체 문자열"

curl -X GET "https://studio-gateway.zerocall.kr/auth-check" \
  -H "x-api-key: $KAT_API_KEY"

Node.js 18 이상에서는 내장 fetch로 같은 요청을 보낼 수 있습니다.

const BASE_URL = 'https://studio-gateway.zerocall.kr';

async function authCheck() {
  const res = await fetch(`${BASE_URL}/auth-check`, {
    headers: { 'x-api-key': process.env.KAT_API_KEY },
  });
  const body = await res.json();
  if (!res.ok) {
    // 에러 형식: { status, code, message }
    throw new Error(`${body.status} ${body.code} ${body.message}`);
  }
  return body.result; // { apiKeyId, userId, name, groupIdList }
}

authCheck().then((me) => console.log(me.name, me.groupIdList));

/auth-check 응답 읽는 법

GET /auth-check는 API 키가 유효한지 확인하는 엔드포인트입니다. 성공하면 공통 성공 응답 구조(code, message, result)의 result에 키 정보가 들어옵니다.

{
  "code": "0",
  "message": "Success",
  "result": {
    "apiKeyId": 123,
    "userId": 456,
    "name": "My API Key",
    "groupIdList": [1, 2, 3]
  }
}

서버가 시작될 때 /auth-check를 한 번 호출해 apiKeyId와 name을 로그에 남겨 두면, 배포 환경에 엉뚱한 키가 들어간 경우를 바로 알아챌 수 있습니다. 키 문자열 자체는 로그에 남기지 않습니다.

키가 없거나 무효하면 401이 반환됩니다. 에러 본문은 아래 형식입니다.

{
  "status": 401,
  "code": "AU002",
  "message": "올바르지 않은 토큰입니다."
}

401이 나오면 환경 변수가 비어 있지 않은지, 키를 복사할 때 앞뒤가 잘리거나 공백·줄바꿈이 들어가지 않았는지, 헤더 이름이 x-api-key인지 차례로 확인합니다.

사용 범위: 문자 발신 API와 비즈니스 기능 API

KAT Cloud API는 종류에 따라 사용 조건이 다릅니다. 자세한 기준은 API 문서의 사용 범위와 권한에 있습니다.

여기서 중요한 것은 어떤 그룹을 검사하느냐입니다. 요청이 접근하는 그룹은 경로에 groupId가 있으면 그 그룹이고, 없으면 API 키에 연결된 모든 그룹입니다. 이 그룹 중 하나라도 조건을 충족하지 못하면 요청 전체가 거부됩니다. 예를 들어 GET /group이나 GET /webhook처럼 경로에 그룹이 없는 요청은, 키에 일반 그룹이 하나만 섞여 있어도 막힐 수 있습니다.

그래서 문서는 비즈니스 요금제 그룹과 일반 그룹을 함께 운영한다면 비즈니스 기능용 API 키에는 비즈니스 요금제 그룹만 연결하라고 권장합니다. 문자 발신만 하는 시스템과 통화 기록·웹훅을 다루는 시스템이 따로 있다면, 키도 용도별로 나누는 편이 관리하기 쉽습니다.

403 AU017 에러 원인 찾기

조건을 충족하지 못한 경우 KAT Cloud는 아래 에러를 반환합니다.

{
  "status": 403,
  "code": "AU017",
  "message": "문자 발신 외 Studio API는 BUSINESS 요금제이거나 별도 허용된 그룹만 사용할 수 있습니다."
}

403은 원인이 두 가지일 수 있습니다. KAT Cloud 문서의 HTTP 상태 표는 403을 그룹 접근 불가 또는 요금제·허용 조건 미충족(AU017)으로 설명합니다. 그러니 상태 코드만 보지 말고 본문의 code를 함께 확인합니다.

AU017이 나왔을 때 어느 그룹이 문제인지 찾으려면, 경로에 groupId가 들어가는 API를 그룹마다 하나씩 호출해 보면 됩니다. 경로에 groupId가 있으면 그 그룹만 검사하기 때문입니다. 아래 스크립트는 GET /payment/group/{groupId}/usage를 그룹별로 호출해 통과한 그룹은 plan을, 막힌 그룹은 에러 코드를 출력합니다.

import os
import requests

BASE_URL = "https://studio-gateway.zerocall.kr"
HEADERS = {"x-api-key": os.environ["KAT_API_KEY"]}


def get(path):
    resp = requests.get(BASE_URL + path, headers=HEADERS, timeout=10)
    body = resp.json()
    if resp.ok and isinstance(body, dict) and "result" in body:
        body = body["result"]
    return resp.status_code, body


status, me = get("/auth-check")
if status != 200:
    raise SystemExit(f"키 확인 실패: {me}")

print(f"키 {me['name']} (apiKeyId={me['apiKeyId']})")
for group_id in me["groupIdList"]:
    status, body = get(f"/payment/group/{group_id}/usage")
    if status == 200:
        print(f"  그룹 {group_id}: 통과, plan={body['plan']}")
    else:
        print(f"  그룹 {group_id}: {status} {body.get('code')} {body.get('message')}")

막힌 그룹이 보이면 방법은 두 가지입니다. 그 그룹의 요금제를 조건에 맞게 바꾸거나, 비즈니스 기능용 키에서 그 그룹을 빼는 것입니다. 별도 허용이 필요한 경우는 도입 문의로 확인합니다. 크레딧·사용량 API를 정기 점검에 쓰는 방법은 사용량·크레딧 API로 비용 모니터링하기에서 이어집니다.

API 키를 안전하게 운영하는 법

API 키는 계정의 거의 모든 기능을 호출할 수 있는 비밀 값입니다. 아래 원칙을 지키면 사고 가능성을 크게 줄일 수 있습니다.

• 키는 서버 환경 변수나 비밀 관리 도구에만 둡니다. 웹 프런트엔드와 모바일 앱에는 넣지 않습니다.
• 저장소에 올리지 않도록 .env 파일을 .gitignore에 넣습니다.
• 로그에는 키 대신 /auth-check의 apiKeyId와 name을 남깁니다.
• 용도별로 키를 나누고, 비즈니스 기능용 키에는 조건을 충족하는 그룹만 연결합니다.
• 키가 노출됐다고 의심되면 콘솔에서 새 키를 발급해 교체하고, 기존 키가 더 이상 쓰이지 않게 정리합니다.

인증과 별개로 400, 404, 429, 500 같은 에러를 어떻게 다룰지는 API 에러 처리와 Rate Limit 대응에 정리했습니다. 처음 연동하는 단계라면 KAT Cloud 시작하기부터 따라 해 보세요. 인증 원문은 API 문서의 인증 항목에 있습니다.

자주 묻는 질문

KAT Cloud API 키는 어디서 발급하나요?

KAT Cloud API 키는 KAT Cloud 콘솔에서 발급하며, 사용자 단위로 만들어집니다. 발급받은 키 전체 문자열을 요청마다 x-api-key 헤더에 그대로 넣어 사용합니다.

/auth-check는 성공하는데 다른 API에서 403이 나는 이유는 무엇인가요?

/auth-check 성공은 API 키가 유효하다는 뜻이고, 403은 키가 접근하는 그룹이 사용 조건을 충족하지 못했다는 뜻입니다. KAT Cloud는 문자 발신 외 API를 비즈니스 요금제 그룹 또는 별도 허용된 그룹에서만 허용하며, 경로에 groupId가 없으면 키에 연결된 모든 그룹을 검사합니다.

401 AU002 에러는 무엇을 뜻하나요?

401 AU002는 KAT Cloud가 요청의 API 키를 올바른 키로 인식하지 못했다는 뜻이며, 메시지는 "올바르지 않은 토큰입니다."입니다. 헤더 이름이 x-api-key인지, 키 문자열이 잘리거나 공백이 섞이지 않았는지 확인합니다.

API 키 하나로 여러 그룹을 다룰 수 있나요?

KAT Cloud API 키에는 여러 그룹이 연결될 수 있으며, 연결된 그룹 ID는 /auth-check 응답의 groupIdList로 확인합니다. 다만 비즈니스 요금제 그룹과 일반 그룹이 섞이면 그룹을 지정하지 않는 요청이 403으로 거부될 수 있으므로, 비즈니스 기능용 키에는 조건을 충족하는 그룹만 연결하는 것이 좋습니다.