API 키와 권한 범위

Ringhum REST API를 사용하면 사용 중인 시스템에서 워크스페이스와 직접 연동할 수 있습니다: 통화와 통화 기록 목록 조회, 어시스턴트 생성, 예약 등록, 연락처 관리, 발신 통화 실행 등입니다. 모든 요청은 하나의 워크스페이스에 속한 API 키로 인증됩니다. 이 문서에서는 키 생성 방법과 모든 엔드포인트가 공유하는 공통 규칙을 다룹니다. 전체 엔드포인트 레퍼런스는 /docs에서 확인할 수 있습니다.

키를 관리할 수 있는 사람

API는 모든 요금제에서 사용할 수 있습니다. 다만 키가 수행할 수 있는 작업은 요금제에 따라 제한됩니다. 예를 들어 요금제의 어시스턴트 한도를 초과하여 생성하려 하면 오류가 반환됩니다.

API 키 생성

1. 사이드바에서 개발자를 엽니다.
2. API 키 카드에서 키 생성을 클릭합니다.
3. 키가 사용되는 위치를 나타내는 키 이름을 입력합니다. 예: "프로덕션 서버".
4. 권한 범위에서 읽기, 쓰기 또는 둘 다를 선택합니다.
5. 키 생성을 클릭합니다.
6. 녹색 상자에서 키를 복사하여 서버의 시크릿 저장소 등 안전한 곳에 보관합니다. 완료를 클릭합니다.

중요: 키는 한 번만 표시됩니다. Ringhum은 키의 지문(fingerprint)만 저장하므로 다시 표시할 수 없습니다. 키를 분실한 경우 새 키를 만들고 기존 키를 취소하세요.

키는 ck_live_로 시작합니다. API 키 표에는 각 키의 이름, 키의 앞부분 문자, 권한 범위, 마지막 사용 시각, 활성 또는 취소됨 상태가 표시됩니다.

권한 범위

모든 키는 조회 전용 엔드포인트를 호출할 수 있습니다. 무언가를 생성, 변경 또는 삭제하는 엔드포인트에는 쓰기 권한이 필요합니다. 예를 들어 통화 실행, 메시지 전송, 예약 등록, 어시스턴트 수정 등이 있습니다. /docs의 레퍼런스에는 이러한 엔드포인트가 표시되어 있습니다. 쓰기 권한이 없는 키로 해당 엔드포인트를 호출하면 403 오류가 반환됩니다.

각 시스템에는 필요한 최소한의 권한만 부여하세요. 리포팅 대시보드에는 읽기 권한만 있으면 충분합니다.

키 취소

1. 개발자 페이지의 API 키 표에서 해당 키를 찾습니다.
2. 취소를 클릭하고 확인합니다.

해당 키를 사용하는 요청은 즉시 401 오류로 실패합니다. 취소된 키는 이력을 확인할 수 있도록 취소됨으로 표시된 채 목록에 남습니다. 키는 수정할 수 없으므로, 권한 범위를 변경하려면 새 키를 만들고 기존 키를 취소하세요.

요청 보내기

• 기본 URL: https://ringhum.com/api/v1
• 인증: 키를 Bearer 토큰으로 전송합니다: Authorization: Bearer ck_live_…
• 형식: 요청과 응답 모두 JSON입니다. 본문이 있는 요청에는 Content-Type: application/json을 함께 보내세요.
• 시간은 UTC 기준 ISO 8601 형식입니다. 전화번호는 E.164 형식입니다(예: +14155550132). ID는 정수입니다.
• 수정은 변경하려는 필드만 포함하여 PATCH를 사용합니다.
• 모든 응답에는 X-Request-Id 헤더가 포함됩니다. 지원팀에 문의할 때 이 값을 함께 알려주세요.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

키가 속한 워크스페이스를 확인하려면 GET /me를 호출하세요.

응답과 페이지네이션

단일 객체는 {"data": {…}} 형태로 반환됩니다. 페이지네이션되는 목록은 meta 객체와 함께 반환됩니다:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

결과를 페이지별로 이동하려면 page와 per_page를 사용하세요. per_page의 기본값은 25이며 최대 100까지 설정할 수 있습니다.

오류

모든 오류는 동일한 형태를 가지며, 코드에서 확인할 수 있는 안정적인 type 값을 포함합니다:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

속도 제한

분당 최대 120건의 요청을 보낼 수 있습니다. 응답에는 X-RateLimit-Limit과 X-RateLimit-Remaining 헤더가 포함됩니다. 한도를 초과하면 대기해야 할 초를 알려주는 Retry-After 헤더와 함께 429 오류가 반환됩니다.

팁: 통화 결과를 폴링하지 마세요. call.ended에 대한 웹훅을 추가하면 통화가 끝났을 때 Ringhum이 요약과 통화 기록을 보내드립니다. 웹훅을 참고하세요.

자주 묻는 질문

기계가 읽을 수 있는 스펙이 있나요? 네. OpenAPI 3.1 설명서는 /api/v1/openapi.json에서 확인할 수 있으며 키가 필요하지 않습니다. 이를 기반으로 클라이언트를 생성할 수 있습니다.

키를 만든 사람이 퇴사하면 키가 작동을 멈추나요? 아니요. 키는 워크스페이스에 속하며 취소되기 전까지 계속 작동합니다. 더 이상 신뢰할 수 없는 키는 취소하세요. 특히 접근 권한이 있던 사람이 퇴사한 경우에는 반드시 취소하세요.

웹페이지에서 API를 사용할 수 있나요? 아니요. 해당 페이지를 여는 누구나 키를 볼 수 있게 됩니다. API는 반드시 서버에서 호출하세요.