AUTH
인증
모든 요청은 Bearer 토큰 한 가지 방식만 씁니다.
POST /v1/oauth/token HTTP/1.1
Host: api.linkhub.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=lh_app_4b19c7
&client_secret=••••••••••••
&scope=user.read+pay.write
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "lh_live_9f2c4a7b1e8d",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "user.read pay.write"
}
Host: api.linkhub.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=lh_app_4b19c7
&client_secret=••••••••••••
&scope=user.read+pay.write
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "lh_live_9f2c4a7b1e8d",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "user.read pay.write"
}
- 토큰 수명 : 1시간 · 만료 5분 전부터 갱신 가능
- 스코프 : 필요한 권한만 요청 · 미사용 스코프는 90일 후 자동 회수
- 비밀키 노출 : 저장소 공개 탐지 시 자동 폐기 후 담당자에게 통지
- IP 허용목록 : 운영 키는 등록된 대역에서만 동작(선택)
- 서명 검증 : 웹훅은 본문 HMAC-SHA256 서명을 헤더로 함께 보냅니다
CATALOG
제공 목록
14개 서비스의 API 를 같은 규약으로 씁니다.
| 영역 | 주요 엔드포인트 | 스코프 | 기본 한도 |
|---|---|---|---|
| 계정 | /v1/users · /v1/users/{id}/profile | user.read | 600 req/분 |
| 메시지 | /v1/messages · /v1/messages/bulk | msg.write | 1,200 req/분 |
| 결제 | /v1/payments · /v1/payments/{id}/cancel | pay.write | 300 req/분 |
| 지도 | /v1/places/search · /v1/routes | map.read | 900 req/분 |
| 커머스 | /v1/products · /v1/orders | commerce.rw | 600 req/분 |
| AI | /v1/chat/completions · /v1/embeddings | ai.invoke | 120 req/분 |
| 스토리지 | /v1/files · /v1/files/{id}/url | file.rw | 600 req/분 |
기본 한도를 넘어야 하는 서비스는 제휴 문의로 상향할 수 있습니다. 상향은 트래픽 패턴을 함께 검토한 뒤 정합니다. 순간 폭주가 예상되는 이벤트가 있으면 최소 7일 전에 알려 주시면 별도 대역을 준비합니다.
ERRORS
오류 규약
오류 응답의 모양은 어느 API 든 같습니다.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
{
"error": {
"code": "rate_limit_exceeded",
"message": "분당 호출 한도를 넘었습니다.",
"detail": "12초 뒤 재시도하십시오.",
"request_id": "req_8Kd2mQ"
}
}
Content-Type: application/json
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
{
"error": {
"code": "rate_limit_exceeded",
"message": "분당 호출 한도를 넘었습니다.",
"detail": "12초 뒤 재시도하십시오.",
"request_id": "req_8Kd2mQ"
}
}
| 코드 | 뜻 | 재시도 |
|---|---|---|
| 400 | 요청 형식이 잘못됨 | 고치기 전까지 무의미 |
| 401 | 토큰 없음 · 만료 | 토큰 재발급 후 1회 |
| 403 | 스코프 부족 · 접근 권한 없음 | 재시도 불가 |
| 404 | 대상 없음 | 재시도 불가 |
| 409 | 중복 요청 · 상태 충돌 | 멱등키 확인 후 |
| 429 | 호출 한도 초과 | Retry-After 만큼 대기 |
| 5xx | 서버 오류 | 지수 백오프로 최대 5회 |
모든 응답에는 request_id 가 들어갑니다. 문의하실 때 이 값을 함께 주시면 해당 요청의 처리 경로를 그대로 추적할 수 있어 원인 파악이 훨씬 빠릅니다. 로그는 30일 보관합니다.
VERSION
버전 정책
쓰던 코드가 어느 날 갑자기 멈추지 않도록 합니다.
안 깨지는 변경은 예고 없이
응답에 필드를 «추가»하는 변경은 수시로 합니다. 모르는 필드는 무시하도록 클라이언트를 만들어 주십시오.
깨지는 변경은 180일 전 고지
필드 삭제·의미 변경·필수 파라미터 추가는 최소 180일 전에 공지하고, 그동안 두 버전을 함께 운영합니다.
폐기 예고는 헤더로도
폐기 예정 엔드포인트는 응답에 Deprecation 과 Sunset 헤더를 실어 보냅니다. 로그만 봐도 알 수 있습니다.
마이그레이션 안내
변경 항목마다 이전 코드와 새 코드를 나란히 보여 주는 문서를 함께 냅니다. 필요하면 담당 엔지니어가 검토를 도와 드립니다.
링크허브의 기술을 먼저 써 보세요
Open API 신청부터 기업용 도입 상담까지 한 곳에서 진행됩니다.