콘텐츠로 이동
GoalTrack 문서

API Key

Key 발급

섹션 제목: “Key 발급”
  1. 앱에서 설정 › API 를 엽니다. 워크스페이스 멤버라면 누구나 자기 Key 를 만들 수 있습니다.
  2. 「새 Key」 에서 이름(용도), 권한, 만료(30일 · 90일 · 365일 · 무기한)를 고르고 발급합니다.
  3. 발급 직후 한 번만 Key 원문(gtk_ 로 시작)이 보입니다. 그 화면을 닫으면 다시 볼 수 없으니 바로 복사해 비밀 저장소에 넣으세요. 목록에는 앞부분만 남습니다.

한 사람이 한 워크스페이스에서 동시에 가질 수 있는 Key 는 20개입니다. 쓰지 않는 Key 는 같은 화면에서 폐기하세요 — 폐기한 Key 는 즉시 401 API_KEY_REVOKED 를 받습니다.

권한(scope)

섹션 제목: “권한(scope)”
권한 할 수 있는 것 누가 고를 수 있나
read (읽기) 이슈·댓글·워크플로 상태·팀·라벨·사이클, 위키 Space·문서, 프로젝트·이니셔티브·마일스톤 조회, 검색, 지표 목록·값 조회 모든 멤버
write (쓰기) 이슈 만들기·고치기·상태·담당자·라벨, 댓글 달기, 위키 문서 만들기·고치기, 프로젝트·이니셔티브·마일스톤 만들기·고치기 소유자·관리자·멤버
metrics:ingest (지표 적재) 지표 값 추가 소유자·관리자·멤버

Key 는 발급한 사람의 신분으로 동작합니다. 그 사람이 지금 볼 수 없는 것은 Key 로도 볼 수 없고, 권한이 줄면 Key 도 같이 줄어듭니다. 발급한 사람이 워크스페이스를 떠나면 그 Key 는 바로 403 이 됩니다 — 오래 돌릴 연동은 팀 공용 계정으로 발급하세요.

호출

섹션 제목: “호출”
터미널 창
curl "https://goaltrack.dyld.kr/api/v1/work_items?limit=50" \
  -H "Authorization: Bearer $GOALTRACK_API_KEY"
  • Key 는 발급한 워크스페이스에 묶여 있어 워크스페이스를 따로 지정하지 않아도 됩니다. x-workspace-slug 헤더를 보내면 Key 의 워크스페이스와 같아야 하고, 다르면 403 WORKSPACE_MISMATCH 입니다.
  • 목록은 { "items": [...], "next_cursor": "…" } 로 옵니다. 다음 쪽은 cursor=<next_cursor> 로 받고, next_cursor 가 null 이면 끝입니다. limit 은 1~200(기본 50)입니다.
  • 이슈 목록·개수(GET /api/v1/work_items · /work_items/counts)를 팀으로 거를 때 team_id(또는 team_key)는 정확히 그 팀의 이슈만 냅니다. 하위 팀 이슈까지 받으려면 include_sub_teams=true 를 함께 보냅니다(그 팀과 아래 팀 전부). team_id·team_key 없이 include_sub_teams=true 만 보내면 400 VALIDATION 입니다.
  • 이슈를 고칠 때는 PATCH 본문에 마지막으로 읽은 version 을 expected_version 으로 함께 보냅니다: { "expected_version": 3, "patch": { "priority": "high" } }. expected_version 이 없으면 412 PRECONDITION_REQUIRED, 그 사이 다른 사람이 고쳤으면 409 VERSION_CONFLICT 입니다. 프로젝트·이니셔티브·마일스톤 고치기(PATCH)도 같습니다. 모르는 필드를 보내면 요청 전체가 400 VALIDATION 으로 거절됩니다.
  • read 권한이 없는 Key 의 쓰기 응답은 이어서 쓰는 데 필요한 값만 담깁니다 — 이슈(만들기·고치기·상태·담당자) { "id", "short_id", "version" } · 문서(만들기·고치기) { "id", "slug", "version" } · 댓글 { "id", "version" } · 라벨 붙이기 { "work_item_id", "label_id" } · 프로젝트·이니셔티브 { "id", "version" } · 마일스톤 { "id", "project_id", "version" }. 409 VERSION_CONFLICT 에도 현재 내용 대신 current_version 만 옵니다.

Key 로 열린 요청

섹션 제목: “Key 로 열린 요청”

아래 요청만 Key 를 받습니다. 표에 없는 요청을 Key 로 부르면 401 UNAUTHORIZED 입니다.

요청 권한 분당 한도
GET /api/v1/work_items read 120
GET /api/v1/work_items/:id read 120
GET /api/v1/work_items/by-short/:shortId read 120
POST /api/v1/work_items write 120
PATCH /api/v1/work_items/:id write 120
POST /api/v1/work_items/:id/status write 120
PATCH /api/v1/work_items/:id/assignee write 120
POST /api/v1/work_items/:id/labels write 120
DELETE /api/v1/work_items/:id/labels/:labelId write 120
GET /api/v1/work_items/:id/comments read 120
POST /api/v1/work_items/:id/comments write 120
GET /api/v1/workflow_states read 120
GET /api/v1/teams read 120
GET /api/v1/labels read 120
GET /api/v1/cycles read 120
GET /api/v1/projects read 120
GET /api/v1/projects/:id read 120
POST /api/v1/projects write 120
PATCH /api/v1/projects/:id write 120
GET /api/v1/initiatives read 120
GET /api/v1/initiatives/:id read 120
POST /api/v1/initiatives write 120
PATCH /api/v1/initiatives/:id write 120
GET /api/v1/milestones read 120
POST /api/v1/milestones write 120
PATCH /api/v1/milestones/:id write 120
GET /api/v1/wiki_spaces read 120
GET /api/v1/documents read 120
GET /api/v1/documents/:id read 120
GET /api/v1/documents/by-slug/:slug read 120
POST /api/v1/documents write 120
PATCH /api/v1/documents/:id write 120
GET /api/v1/search read 120
GET /api/v1/metric_definitions read 120
GET /api/v1/metric_definitions/:id/values read 120
GET /api/v1/auth/whoami read 120
POST <수집 주소> metrics:ingest 120
POST <수집 주소>/bulk metrics:ingest 20

<수집 주소> 는 지표 값 적재에서 설명합니다.

요청 한도

섹션 제목: “요청 한도”
  • 한도는 Key 하나가 보내는 요청을 모두 합쳐 셉니다 — 표의 요청 어느 것을 섞어 보내도 1분에 120번까지이고, 1분마다 다시 찹니다. 배치 수집은 그 안에서 따로 1분에 20번까지입니다. 넘으면 429 와 함께 Retry-After 헤더(초)가 옵니다. 그 시간만큼 기다린 뒤 다시 보내세요.
  • 이 밖에도 남용을 막는 상한이 있습니다(잘못된 Key 를 반복해서 보내는 경우 등). 어느 한도든 429 를 받으면 Retry-After 만큼 기다린 뒤 다시 보내세요.