API 개요
이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.
이 문서는 Capgo 클라우드의 API 공용 API에 대한 설명입니다. API를 사용하면 조직, 디바이스, 채널, 번들을 포함한 Capgo 리소스를 프로그래밍 방식으로 관리할 수 있습니다. 이 API는 RESTful 방식으로 설계되었으며 표준 HTTP 메서드를 사용합니다.
모든 API 엔드포인트는 인증이 필요합니다. 요청을 인증하려면 API 키를 x-api-key 헤더에 추가하거나, 다음과 같이 전송하세요 Authorization: Bearer YOUR_API_KEY.
예시:
curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/organization/이 authorization raw 키를 그대로 담은 헤더(prefix Bearer 없이)도 기존 통합을 위해 계속 허용되지만, x-api-key 보안 해시 키를 포함한 모든 키 유형에는 이 헤더를 권장합니다.
AI 에이전트와 기타 OAuth 클라이언트는 OAuth 2.0(PKCE 및 dynamic client registration을 사용하는 authorization code)을 통해 키를 받을 수 있습니다. issuer는 https://capgo.app, 메타데이터 포함: https://capgo.app/.well-known/oauth-authorization-server. 사용자가 권한을 부여할 조직을 선택하면, 액세스 토큰은 Bearer 토큰으로 전송되는 Capgo API 키가 됩니다.
버전 관리
“Versioning” 섹션API은 날짜별로 버전이 관리됩니다. 다음 capgo_api 요청 헤더를 사용하여 버전을 고정할 수 있습니다:
curl -H "x-api-key: YOUR_API_KEY" -H "capgo_api: 2025-10-01" https://api.capgo.app/organization/헤더가 없으면 현재 기준인 다음의 기본 버전을 가져옵니다: 2025-10-01. 특정 버전 내의 변경 사항은 추가적인 방식(additive)으로 이루어집니다: 새로운 엔드포인트, 새로운 선택적 파라미터, 새로운 응답 필드 등이 추가됩니다. Breaking change는 새로운 날짜 버전으로 배포되며, 이전 날짜에 고정된 클라이언트는 기존 동작을 유지합니다. 알 수 없거나 잘못된 형식의 버전은 다음을 반환합니다: 400 unsupported_capgo_api_version 또는 400 invalid_capgo_api_version.
작업(operation)이나 필드를 삭제하는 것은 breaking change에 해당하므로, 반드시 새로운 날짜 버전에서만 수행됩니다. 현재 deprecated된 항목은 없습니다. 향후 deprecated되는 항목이 생기면 해당 작업에 다음과 같이 표시됩니다: deprecated: true 플러그인의 OpenAPI 명세, 응답에 다음이 포함됩니다: Deprecation 헤더 (RFC 9745) 및 Sunset 헤더 (RFC 8594) (기존 동작 종료 날짜 포함). 변경 사항은 릴리스 노트.
API는 공정한 사용을 위해 rate limiting을 적용합니다. 현재 제한 사항은 다음과 같습니다:
- API 키당 분당 2,000회 요청
- bundle upload 경로의 경우 API 키당 분당 20,000회 요청
- 15분 내 IP당 20회의 잘못된 API 키 사용 시 해당 IP는 15분간 차단됩니다
모든 응답은 다음의 RateLimit-Policy 및 RateLimit headers (IETF 초안):
RateLimit-Policy: "apikey";q=2000;w=60RateLimit: "apikey";r=1995;t=42q 는 할당량, w 는 초 단위의 윈도우 시간, r 는 남은 요청 횟수이며 t 윈도우가 초기화될 때까지 남은 초입니다. 제한을 초과하면 429 (Too Many Requests) 응답과 함께 다음 정보가 포함된 Retry-After 초 단위 헤더가 반환됩니다.
디바이스 채널 변경
“Device channel changes” 섹션Device channel changes는 API 플러그인을 사용하며, 체험판을 포함한 모든 플랜에 적용되는 별도의 남용 방지 제한이 있습니다:
- 디바이스는 각 채널 작업당 초당 최대 5회의 요청을 보낼 수 있습니다 ("
set,get,delete, 또는list"). 이 제한은 앱, 디바이스 및 작업 단위로 적용됩니다. - 60초 이내에 동일한 디바이스를 동일한 채널로 두 번 이상 설정하려고 하면 429 응답이 반환됩니다. 초당 제한이 초기화된 후에는 다른 채널로 전환할 수 있습니다.
- 각 앱 및 IP 주소에는 분당 1,000회의 채널 요청 제한이 추가로 적용됩니다.
이 제한은 계정 전체에 적용되지 않습니다. 채널 스위처가 최근에 선택한 채널로 다시 돌아갈 수 있는 경우, 429 응답에 포함된 retryAfterSeconds 시간만큼 기다린 후 다시 시도하세요.
응답 형식
“Response Format” 섹션모든 응답은 JSON 형식입니다. 성공 응답에는 보통 다음 중 하나가 포함됩니다: data 객체 또는 status 필드가 포함됩니다. 에러 응답에는 기계가 읽을 수 있는 error code, 사람이 읽을 수 있는 message, 그리고 선택 사항인 moreInfo 상세 정보가 포함됩니다.
성공 응답 예시:
{ "status": "ok", "data": { ... }}에러 응답 예시:
{ "error": "invalid_apikey", "message": "Invalid apikey", "moreInfo": {}}사용 가능한 엔드포인트
“사용 가능한 엔드포인트” 섹션모범 사례
“권장 사항” 섹션- 에러 핸들링: 항상 에러 응답을 확인하고 적절하게 처리해야 합니다.
- 요청 제한: Rate limit에 도달할 경우 Exponential backoff를 구현하세요.
- 캐싱: API 호출을 줄이기 위해 적절한 경우 응답을 캐싱하세요.
- 버전 관리: changelog를 통해 API 변경 사항을 확인하세요
API Overview에서 계속하기
“API Overview에서 계속하기” 섹션사용 중이라면 API 개요 인증 및 계정 흐름을 설계할 때, 이를 다음 항목과 연결하세요: @capgo/capacitor-social-login @capgo/capacitor-social-login의 구현 세부 사항은, @capgo/capacitor-passkey @capgo/capacitor-passkey의 구현 세부 사항은 @capgo/capacitor-native-biometric @capgo/capacitor-native-biometric의 구현 세부 사항은, 2단계 인증 2단계 인증(Two-factor authentication)의 구현 세부 사항은, SSO (기업용) SSO (Enterprise)의 구현 세부 사항은.