API에서 Caputchin 관리하기

대시보드에서 할 수 있는 모든 것을, 결제만 빼고, 코드에서도 할 수 있습니다. Caputchin은 하나의 관리 API를 노출하고, 그 위에 세 표면이 앉습니다: 이 HTTP API를 직접, AI 에이전트를 위한 MCP 서버, 그리고 코드형 인프라를 위한 Terraform과 OpenTofu 프로바이더. 그것들은 가장자리에서만 다릅니다; 무엇을 쓰든 같은 검증, 권한, 감사 로깅이 적용됩니다.

셋 모두 같은 자격 증명으로 인증합니다: 한 번 발급하는 액세스 토큰.

액세스 토큰 발급하기

토큰을 Bearer 헤더로 보냅니다. 두 종류가 있으며, Personal Access Token과 팀 토큰 아래에 온전히 다룹니다:

당신 자신의 전체 계정 자동화에는 Personal Access Token을; 범위 지정된 최소 권한 접근(팀 하나만 손대는 CI 작업)에는 팀 토큰을 쓰세요. 둘 다 아래 모든 곳에서 동작합니다. 토큰 값은 생성 시 한 번 표시되니, 그것을 시크릿 저장소에 복사하세요.

베이스 URL과 인증

관리 API의 뿌리는:

https://caputchin.com/api/v1/management

모든 요청은 토큰을 Bearer 헤더로 지닙니다:

Authorization: Bearer cpt_pat_...

요청과 응답은 JSON입니다. 당신의 토큰이 허용되지 않은 호출은 403을 돌려주고; 알 수 없거나 취소된 토큰은 401을 돌려줍니다.

동작하는 예제: 사이트 키 만들기

당신의 shop-team 팀에 새 사이트 키를 원한다고 합시다. 먼저 팀을 나열해 그 id를 찾고, 그다음 그 안에 키를 만드세요.

# 1. Find the troop id.
curl -s https://caputchin.com/api/v1/management/troops \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN"
# → { "troops": [ { "id": "troop_…", "name": "shop-team", … }, … ] }

# 2. Create a site key in that troop.
curl -s -X POST https://caputchin.com/api/v1/management/sites \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "shop-frontend", "troop_id": "troop_…" }'
# → { "id": "site_…", "key": "cpt_pub_…", "secret": "cpt_sec_…", … }

응답은 새 키의 공개 key와 그 secret을 지닙니다. 시크릿은 한 번, 여기서 표시되니, 지금 붙잡으세요; 당신은 백엔드에서 그것으로 검증할 것입니다. troop_id를 생략하면 키가 당신의 Personal 팀에 떨어집니다.

그것이 패턴 전체입니다: Bearer 토큰, JSON 본문, 작업당 한 호출. 나열은 GET, 생성은 POST, 갱신은 PATCH 또는 PUT, 제거는 DELETE로, 베이스 URL 아래의 리소스 경로에 대해.

전체 레퍼런스

모든 엔드포인트가, 그 파라미터, 요청과 응답 스키마, 그리고 당신의 토큰으로 인증하는 내장 "try it" 패널과 함께, 대화형 API 레퍼런스에 있습니다. 그것은 API가 빌드되는 같은 OpenAPI 명세에서 생성되니, 라이브 표면에서 결코 어긋나지 않습니다. 당신 자신의 클라이언트 생성기를 거기 링크된 명세로 향하게 하세요.

함께 보기

• Personal Access Token: 마스터 자격 증명과 그 사용을 추적하는 법.
• MCP 서버 쓰기: 같은 API를, AI 에이전트가 몰아감.
• Terraform 또는 OpenTofu 쓰기: 같은 API를, 코드형 인프라로.
• 대화형 API 레퍼런스: 모든 엔드포인트와 스키마.