앱을 API에 연결하기
API 키를 생성하고, Zapier 같은 앱을 승인하고, 접근 범위를 제어하세요.
고급 사용자를 위한 안내
이 페이지는 ITB의 개발자용 기능인 API 키와 OAuth 앱 연결을 다룹니다. 이벤트가 발생할 때 다른 도구로 데이터를 보내기만 하면 된다면 먼저 웹훅을 확인하세요.
외부 앱이 Go Toolbelt 외부 API를 통해 계정에 접근하는 방법은 두 가지입니다:
- API 키 — 키를 생성해서 직접 만든 스크립트나 키를 요구하는 도구에 붙여넣습니다. 서버 간 연동과 맞춤 소프트웨어에 적합합니다.
- OAuth — Zapier 같은 앱이 ITB 동의 화면으로 안내하고, 클릭 한 번으로 접근을 승인합니다. 키를 다룰 필요가 없습니다.
시작하기 전에
- API 키와 웹훅은 설정연동에 있습니다.
- API 키는 본인 계정의 데이터에만 작동합니다. 생성할 때 선택한 권한만 부여되며, 거의 모든 권한은 읽기 전용입니다(예외는 웹훅 관리).
- 활성 API 키는 한 번에 최대 10개까지 가질 수 있습니다.
API 키 생성하기
키 이름 지정 및 권한 선택
API 키 생성을 클릭합니다. 용도를 알 수 있는 이름(예: "Zapier 연동")을 지정한 다음 필요한 권한을 체크합니다. **주문(읽기)**과 **연락처(읽기)**는 미리 선택되어 있습니다. 전체 목록은 아래 권한 표를 확인하세요.
키 복사
키 생성을 클릭합니다. 새 키는 한 번만 표시됩니다 — 복사 버튼으로 복사하여 안전한 곳에 보관하세요.
지금 키를 복사하세요
키는 한 번만 표시됩니다. 분실한 경우 해지하고 새 키를 만드세요 — 다시 볼 수 있는 방법은 없습니다.
확인해야 할 내용
새 키가 이름, 권한 배지, 생성 날짜와 함께 API 키 목록에 나타납니다. 앱이 키를 사용하기 시작하면 마지막 사용 날짜도 표시됩니다.
개발자라면: https://api.gotoolbelt.com/v1/...에 요청할 때 X-API-Key 헤더에 키를 담아 보내세요. 대화형 엔드포인트 문서는 api.gotoolbelt.com/docs에 있습니다(API 키 카드에서도 연결됩니다).
API 키 해지하기
API 키 목록에서 키를 찾아 옆의 휴지통 버튼을 클릭합니다.
해지로 확정합니다. 이 키를 사용하는 모든 연동이 즉시 작동을 멈춥니다.
OAuth로 앱 승인하기
일부 앱(Zapier, Make 및 기타 등록된 파트너)은 API 키 대신 OAuth로 연결합니다. 사용자 입장에서 흐름은 다음과 같습니다:
외부 앱에서 ITB / Go Toolbelt 계정 연결을 선택합니다. 앱이 ITB 동의 화면으로 안내합니다(아직 로그인하지 않았다면 먼저 로그인하라는 요청이 표시됩니다).
동의 화면에는 앱 이름, 로그인 중인 계정, 앱이 할 수 있게 되는 작업이 정확히 표시됩니다 — 예: "Orders 및 주문 세부 정보 보기".
액세스 허용을 클릭하여 승인하거나 거부를 클릭하여 취소합니다. 어느 쪽이든 앱으로 돌아갑니다.
앱은 등록된 권한보다 더 많은 권한을 받을 수 없습니다 — 아래 권한 표와 같은 목록입니다.
자체 OAuth 앱은 등록할 수 없습니다
OAuth 앱은 계정 설정이 아니라 ITB 팀에서 등록합니다. 본인만 사용할 맞춤 연동을 만든다면 API 키를 사용하세요.
Zapier 또는 Make 연결하기
Zapier와 Make는 위의 OAuth 흐름으로 연결합니다 — 앱 디렉토리에서 ITB / Go Toolbelt 앱을 검색하고 연결을 클릭하세요. Zap 트리거를 설정하면 Zapier가 계정에 해당 웹훅 구독을 자동으로 생성하므로, 웹훅에서 직접 구성할 것은 없습니다.
사용 가능한 Zapier 트리거: Order 생성됨, 승인됨, 완료됨, 일정 변경됨, 상태 변경됨, 그리고 청구서 결제됨 및 Report 게시됨. 정확한 페이로드는 웹훅 이벤트 참고 자료에 문서화되어 있습니다.
권한 참고
API 키 또는 OAuth 앱이 가질 수 있는 권한(스코프)은 다음과 같습니다:
| 권한 | 스코프 | 허용 범위 |
|---|---|---|
| 주문(읽기) | orders:read | Orders 및 세부 정보 보기 |
| 연락처(읽기) | contacts:read | 연락처 보기 |
| 청구서 및 청구(읽기) | billing:read | 청구서 및 거래 보기 |
| 캘린더(읽기) | calendar:read | 캘린더 일정 및 가용 시간 보기 |
| 템플릿(읽기) | templates:read | Report 템플릿 보기 |
| 회사 프로필(읽기) | company:read | 회사 프로필 보기 |
| 팀원(읽기) | team:read | 팀원 보기 |
| 알림(읽기) | notifications:read | 알림 설정 보기 |
| 웹훅(읽기) | webhooks:read | 웹훅 엔드포인트 구성 보기 |
| 웹훅(관리) | webhooks:write | 웹훅 엔드포인트 생성, 업데이트, 삭제 |
**웹훅(관리)**를 제외한 모든 권한은 읽기 전용입니다 — 키나 연결된 앱은 API를 통해 Orders, 연락처, 청구서를 생성, 변경 또는 삭제할 수 없습니다.
문제가 발생한 경우
- 연동이 갑자기 작동을 멈췄어요 — API 키가 해지되지 않았는지(해지는 즉시 적용됨), 연동에 필요한 모든 권한이 키에 있는지 확인하세요. 권한이 없는 요청은 "missing required scope" 오류와 함께 거부됩니다.
- "Invalid API key" 오류 — 키를 잘못 입력했거나 해지되었습니다. 키는 생성 후 다시 볼 수 없으므로 새 키를 만드세요.
- 키 생성 버튼이 반응하지 않아요 — 이름과 최소 하나의 권한 체크가 필요합니다. 10개 키 제한에 도달했을 수도 있습니다(먼저 이전 키를 해지하세요).