English

인증

MOAI Cloud API는 X-API-Key 헤더 기반 인증을 사용합니다. JWT나 OAuth 절차 없이 1줄로 모든 모듈을 호출할 수 있습니다.

API Key 발급

대시보드의 API Keys 메뉴에서 Create Key 버튼으로 새 키를 발급할 수 있습니다. 발급된 시크릿은 생성 직후 1회만 노출되며, 이후에는 prefix(예: mcl_live_3f2a) 만 확인할 수 있으니 안전한 시크릿 매니저에 저장해 주세요.

  • mcl_live_ prefix — 운영(Production) 키
  • mcl_test_ prefix — 테스트(Sandbox) 키, quota 별도 카운트

요청 헤더

모든 요청은 다음 두 헤더가 필요합니다.

http
X-API-Key: mcl_live_3f2ad5e9c1b84f6a92d7e0f1b2c3d4e5
Content-Type: application/json

예제

cURL — Lingua 카테고리 목록 조회

bash
curl -H "X-API-Key: $MOAI_API_KEY" \
  https://api.moai.page/v1/lingua/categories

Node.js SDK

typescript
import { MoaiCloud } from '@moai/cloud-sdk';

const client = new MoaiCloud({ apiKey: process.env.MOAI_API_KEY! });

const categories = await client.lingua.listCategories();
console.log(categories);

보안 권장: 시크릿은 환경 변수 또는 GCP Secret Manager / AWS Secrets Manager에 저장하세요. 모바일 앱 번들에 직접 포함하지 말고, 자체 백엔드에서 프록시하여 호출하는 것을 권장합니다.

키 회수 및 교체

키 노출이 의심될 경우 대시보드에서 Revoke 버튼으로 즉시 무효화할 수 있습니다. 무중단 교체를 위해 신규 키를 먼저 배포한 뒤 구 키를 회수하는 순서를 권장합니다.

오류 처리

  • 401 CLOUD_API_KEY_INVALID — 헤더 누락 또는 잘못된 키
  • 401 CLOUD_API_KEY_REVOKED — 관리자가 회수한 키
  • 403 CLOUD_MODULE_NOT_ENABLED — 해당 모듈 미구독
  • 429 QUOTA_EXCEEDED — 월 quota 초과

상세 코드 매트릭스는 에러 코드 페이지를 참고하세요.

Previous빠른 시작NextSDK 설치