첫 API 연결 테스트

고객사 서버에서 /health, /api/status, /api/ping(GET/POST) 요청을 보내 연결 상태를 확인합니다.

1) API Key 적용 방법

API Key는 고객사 백엔드 설정 파일 또는 환경 변수에 저장합니다. 브라우저 코드에는 저장하지 않습니다.

현재 샘플 코드 제공 언어는 PHP, Node.js만 지원합니다.

언어/환경 권장 위치 설정 예시
PHP 루트 설정 파일 또는 루트 외부 파일 broadcast_api_config.php
Node.js 프로젝트 설정 파일 또는 환경 변수 config.js
필수 헤더 
X-API-Key: {발급받은 API Key}

2) API 공통 명세

Base URL: https://{your-domain}

Header 필수 설명
X-API-Key /api/* 필수 발급된 API Key
Content-Type POST 시 필수 application/json
Accept 권장 application/json

3) Endpoint 상세

3-1. Health Check

GET /health

서버 기본 기동 상태를 확인합니다. API Key는 필요 없습니다.

Request

curl -sS "{BASE_URL}/health"

Response 200

{
  "status": "ok"
}
3-2. API Status

GET /api/status

API Key 검증 후 서비스 상태와 키 클레임 정보를 반환합니다.

Header

X-API-Key: {API_KEY}

Request

curl -sS \
  -H "X-API-Key: {API_KEY}" \
  "{BASE_URL}/api/status"

Response 200

{
  "service": "broadcast-api",
  "status": "ok",
  "environment": "Production",
  "startedAtUtc": "2026-01-01T00:00:00Z",
  "uptimeSeconds": 12345,
  "key": {
    "company": "YOUR_COMPANY",
    "email": "admin@example.com",
    "exp": "YYYY-MM-DD or 0000-00-00",
    "tier": "PRO"
  },
  "checks": {
    "api": true,
    "awsRegionConfigured": true,
    "awsCredentialsConfigured": true,
    "ivsServiceReady": true,
    "ivsChatServiceReady": true,
    "broadcastServiceReady": true
  },
  "awsChecks": {
    "region": "ap-northeast-2",
    "sts": {
      "ok": true,
      "errorCode": null,
      "message": null
    },
    "ivs": {
      "ok": true,
      "errorCode": null,
      "message": null
    },
    "ivsChat": {
      "ok": true,
      "errorCode": null,
      "message": null
    }
  }
}

Response 401 (헤더 누락)

{
  "errorCode": "UNAUTHORIZED_API_KEY",
  "message": "X-API-Key is required."
}

Response 403 (검증 실패)

{
  "errorCode": "INVALID_API_KEY_SIGNATURE",
  "message": "API key verification failed."
}
3-3. Ping

GET /api/ping, POST /api/ping

요청/응답 왕복 테스트 API입니다. 두 요청 모두 API Key가 필요합니다.

Header

X-API-Key: {API_KEY}

GET Request

curl -sS \
  -H "X-API-Key: {API_KEY}" \
  "{BASE_URL}/api/ping"

GET Response 200

{
  "ok": true,
  "message": "pong",
  "serverTimeUtc": "2026-01-01T00:00:00Z",
  "traceId": "TRACE_ID_EXAMPLE"
}

POST Header

Content-Type: application/json
X-API-Key: {API_KEY}

Body Parameter

필드 타입 필수 설명
message string 선택 클라이언트 테스트 메시지

Request

curl -sS -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {API_KEY}" \
  -d "{\"message\":\"hello\"}" \
  "{BASE_URL}/api/ping"

Response 200

{
  "ok": true,
  "message": "pong",
  "requestMessage": "hello",
  "serverTimeUtc": "2026-01-01T00:00:00Z",
  "traceId": "TRACE_ID_EXAMPLE"
}
공통 에러 코드(요약)
  • UNAUTHORIZED_API_KEY
  • INVALID_API_KEY_FORMAT
  • INVALID_API_KEY_ENCODING
  • INVALID_API_KEY_LENGTH
  • INVALID_API_KEY_SIGNATURE
  • INVALID_API_KEY_PAYLOAD
  • INVALID_API_KEY_CLAIMS
  • INVALID_API_KEY_EMAIL
  • INVALID_API_KEY_EXP
  • EXPIRED_API_KEY
  • INVALID_API_KEY_TIER

4) 기타 보안 안내

  • 브라우저에서 API 서버를 직접 호출하지 않습니다.
  • 고객사 백엔드가 Server-to-Server 방식으로 호출합니다.
  • 설정 파일은 웹 접근 차단을 적용합니다.
  • 키 노출 의심 시 즉시 교체하고 기존 키를 폐기합니다.
.htaccess 접근 차단 예시

Apache(PHP)에서는 설정 파일만 차단하고, 테스트는 CLI로 실행합니다. 

<Files "broadcast_api_config.php">
  Require all denied
</Files>

Node.js 환경에는 .htaccess가 없으므로 config.js/.env 파일을 웹 루트 밖에 두고 파일 권한으로 보호합니다.

샘플 코드 다운로드