API 키와 액세스 토큰

API 키는 내 프로그램이 LinkHarbor API에 들어오는 수단입니다. 키는 사람이 아니라 워크스페이스에 속하며, 스코프로 허용한 일만 정확히 할 수 있습니다. 실제 호출에는 키를 수명이 짧은 액세스 토큰으로 교환해 씁니다.

#누가 API 키를 만들 수 있나요?

• 워크스페이스의 소유자와 관리자. 편집자와 뷰어는 “콜백 및 API”에서 “연결된 앱” 카드만 봄
• Creator Pro부터. Creator Free에서는 카드에 “API 키는 Creator Pro부터 사용할 수 있습니다.”가 표시됨
• 동시에 활성화할 수 있는 키: Creator Pro 최대 5개, Creator Agency 최대 20개, Enterprise 최대 50개

한도에 도달하면 키 만들기가 409 limit_reached로 실패합니다. 먼저 더 이상 필요 없는 키를 삭제하세요.

#API 키 만들기

1. 내비게이션에서 “콜백 및 API”를 엽니다
2. “API 키” 카드에서 “+ 새 키 만들기”를 클릭합니다
3. “이름 (선택)”에 나중에 알아볼 수 있는 이름을 입력합니다. 예: “CI/CD 파이프라인”, “쇼핑몰 동기화”
4. “스코프”에서 영역마다 “읽기” 또는 “쓰기”를 고릅니다
5. “키 만들기”를 클릭합니다
6. “키 시크릿 (비공개)”을 바로 복사해 안전한 곳에 보관합니다
7. 대화상자를 닫습니다. 키 ID는 목록에서 언제든 볼 수 있습니다

“이름 (선택)”

최대 64자입니다. 이름이 없으면 목록에 “API 키 #ID”로 표시됩니다.

“스코프”

하나 이상 필수입니다. “쓰기”에는 같은 영역의 “읽기”가 자동으로 포함됩니다. 통계와 후원 결제는 읽기 전용, 워크스페이스 템플릿은 쓰기 전용입니다. 모든 스코프는 스코프 자세히 보기에서 설명합니다.

“키 시크릿 (비공개)”

lt_로 시작하며 정확히 한 번만 표시됩니다(“⚠️ 한 번만 표시됩니다. 지금 복사하세요!”). LinkHarbor는 그 해시만 저장하므로 나중에 다시 보여 줄 수 없습니다.

“키 ID:”

숫자와 대문자 A–F로 된 16자입니다. 예: 6F668EA6598B0692. 비밀이 아니며 목록에 복사 버튼과 함께 표시됩니다.

#키 목록

활성 키마다 이름, “활성” 상태, 키 ID, 스코프, “생성일:”, “마지막 사용:” 또는 “아직 사용 안 함”이 표시됩니다. 마지막 사용 시각은 키로 호출할 때마다, 최대 1분에 한 번 업데이트됩니다. “↺ 새로고침”으로 목록을 다시 불러옵니다.

#키를 액세스 토큰으로 교환하기

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

액세스 토큰입니다. 모든 요청에 Authorization: Bearer <token>으로 보냅니다.

expires_in

유효 시간(초)이며 900, 즉 15분입니다. 리프레시 토큰은 없습니다. 만료되면 키 ID와 시크릿으로 새 토큰을 받으면 됩니다.

토큰은 워크스페이스를 대표하며 키의 스코프를 그대로 가집니다. 사람처럼 역할을 갖지는 않습니다. 대시보드가 소유자와 관리자에게만 허용하는 엔드포인트(멤버, 결제, 도메인 관리, 웹훅, 워크스페이스 설정)는 API 키의 토큰에 항상 거부됩니다. 예외는 해당 스코프로 작동하는 단축 링크와 워크스페이스 템플릿, 그리고 read:workspaces로 콜백 시크릿을 읽는 것(평문 시크릿 제외)입니다.

#실패한 시도와 잠금

api_key_locked에서는 남은 시간이 details.retry_after_sec에 있습니다. 교환에 성공하면 횟수가 초기화됩니다.

#키 삭제와 교체

1. 키 옆의 “삭제”를 클릭합니다
2. 확인을 위해 DELETE를 입력합니다
3. “영구 삭제”를 클릭합니다

키는 즉시 작동을 멈춥니다. 이미 발급된 액세스 토큰도 그 순간부터 작동하지 않으며 401 invalid_token을 받습니다. 교체 버튼은 없습니다. 키를 바꾸려면 새 키를 만들고, 프로그램을 새 키로 옮긴 뒤 이전 키를 삭제하세요.

#플랜이 내려갈 때

워크스페이스가 Creator Free로 바뀌면 모든 API 키가 폐기됩니다. 키 수가 더 적은 플랜으로 바뀌면 가장 새로운 키가 남고 나머지는 폐기됩니다. 폐기된 키는 나중에 업그레이드해도 돌아오지 않으므로 그때 새로 만드세요. 소유자는 비활성화된 기능을 나열한 이메일을 받습니다. 자세한 내용은 해지와 다운그레이드에 있습니다.

#안전하게 보관하기

• 시크릿은 시크릿 관리 도구나 환경 변수에만 두고, 소스 코드나 Git 저장소에는 절대 넣지 않기
• 브라우저나 사용자 기기의 앱에서 실행되는 코드에 절대 쓰지 않기
• 애플리케이션마다 가능한 한 적은 스코프로 별도의 키 만들기
• 더 이상 필요 없는 키는 바로 삭제하기
• 유출이 의심되면 키를 삭제하고 새로 만들기