OAuth 2.1로 멀티테넌트 연동 구축하기
사용자가 자신의 Crisphive 비즈니스를 여러분의 제품에 연결할 수 있게 하세요. 동의 화면이 있는 OAuth 2.1 방식으로, API 키를 복사하는 일이 전혀 없습니다.
API 키는 자신의 비즈니스를 인증합니다. 다른 Crisphive 비즈니스가 연결하는 제품 — CRM 동기화, 예약 위젯, AI 에이전트 커넥터 — 을 만들 때는 내장 OAuth 2.1 인가 서버를 사용하세요. 각 비즈니스 소유자가 동의 화면에서 앱을 승인하면, 앱은 그 소유자의 테넌트에 바인딩된 토큰을 받습니다.
/v1 API와 /mcp 엔드포인트입니다. API 키와 똑같이 Authorization: Bearer <access_token>을 보내세요.플로우
서버는 최신 OAuth 2.1 초안을 구현합니다. PKCE(S256)는 필수이고, 클라이언트는 퍼블릭(시크릿 없음)이며, 등록은 동적입니다 — 수동 앱 심사 단계가 없습니다:
| 단계 | 요청 |
|---|---|
| 1. 인가 서버 발견 | GET /.well-known/oauth-authorization-server(RFC 8414) → 엔드포인트 URL, 지원 그랜트 |
| 2. 등록 | POST /oauth/register(RFC 7591 동적 클라이언트 등록) → client_id |
| 3. 인가 | GET /oauth/authorize?… — 비즈니스 소유자가 Crisphive에 로그인하고 동의합니다 |
| 4. 교환 | POST /oauth/token(grant_type=authorization_code, code, code_verifier) → { access_token, refresh_token, expires_in } |
| 5. 갱신 | POST /oauth/token(grant_type=refresh_token) → 로테이션된 토큰 쌍(이전 refresh 토큰은 일회용) |
토큰
토큰은 동의한 소유자의 비즈니스, 리전, 환경에 바인딩되므로 절대 다른 테넌트에 접근하거나 라이브↔샌드박스를 전환할 수 없습니다. 접근을 제한하려면 더 좁은 scope(공백으로 구분된 권한 코드, 예: customers_view job_requests_view)를 요청하고, 전체 비즈니스 접근이 필요하면 생략하세요. 액세스 토큰은 약 1시간 유효하며, 일회용 refresh 토큰으로 갱신해 연결을 유지하세요.
연결 유효 기간
연결은 서로 독립적인 두 개의 시계로 관리됩니다. 매일 사용되는 연동은 일정에 따라 끊기는 일이 없고, 잊힌 연동은 스스로 만료됩니다.
- 유휴 기간 — 30일. 토큰을 갱신할 때마다 30일 동안 유효한 새 refresh 토큰이 발급됩니다. 연결을 계속 사용하면 무기한 연장되고, 30일 동안 사용하지 않으면 만료됩니다.
- 절대 상한 — 90일. 활동 여부와 관계없이 연결은 비즈니스 소유자가 승인한 시점으로부터 90일 후에 종료됩니다. 비즈니스는 Developers → MCP connections에서 연결별로 이 값을 1일부터 365일까지 설정할 수 있으며, 카운트다운은 변경 시점이 아니라 최초 승인 시점부터 계산됩니다.
두 시계 중 하나라도 다 되면 갱신이 실패하고(OAUTH_GRANT_EXPIRED) 소유자가 동의 화면에서 앱을 다시 승인해야 합니다. 갱신 실패는 재시도 가능한 오류가 아니라 항상 "인가 플로우를 다시 시작하라"는 신호로 처리하세요. 연결이 만료되기 14일 전에 비즈니스의 소유자와 관리자에게 이메일이 발송됩니다 — 다시 승인하려면 소유자가 브라우저에서 작업해야 하므로, 키보다 더 일찍 경고가 발송됩니다.
API 호출하기
curl "https://api.crisphive.com/v1/customers" \ -H "Authorization: Bearer <access_token>"
AI 에이전트 커넥터를 만들고 있나요? MCP 서버가 바로 이 플로우를 사용합니다. 규격을 준수하는 MCP 클라이언트가 자동으로 실행하므로 보통 OAuth 코드를 전혀 작성하지 않아도 됩니다.