API 키와 스코프

Tahoe API로 보내는 모든 요청에는 API 키가 들어갑니다. 키는 세 가지를 정합니다. 요청이 어느 워크스페이스를 읽는지, 어떤 종류의 데이터를 볼 수 있는지(스코프), 어디서 사용할 수 있는지입니다. 이 페이지에서는 키를 받는 방법, 키를 보내는 방법, 31개 스코프가 각각 허용하는 것, 키를 교체하거나 폐기하는 방법을 설명합니다.

키 받기#

워크스페이스 소유자와 관리자가 직접 키를 만듭니다. 설정을 열고 개발자를 선택한 뒤 키 만들기를 누르세요. 다음을 정합니다.

• “Acme HRIS sync”처럼 키에 붙일 이름
• test 키인지 live 키인지(둘 다 하나씩 만들 수도 있습니다)
• 아래 표에서 그 키에 필요한 스코프
• 키를 쓸 기간(1일에서 365일)
• 선택 사항으로, 키를 사용할 IP 주소나 대역

API 약관에도 동의해야 합니다. 시크릿은 한 번만 표시되므로, 대화상자를 닫기 전에 시크릿 관리 도구에 복사해 두세요. 키는 만든 워크스페이스에 속하며 다른 워크스페이스는 읽을 수 없습니다.

필요한 만큼만 가장 좁은 범위의 스코프를 선택하세요. 스코프는 키를 만들 때 정해지므로, 나중에 스코프를 추가하려면 새 키가 필요합니다.

키 보내기#

모든 요청의 Authorization 헤더에 키를 bearer 토큰으로 보내세요. 다른 방식은 받지 않습니다. 쿼리 파라미터, 쿠키, Basic 인증 모두 사용할 수 없습니다.

GET /api/partner/v1/jobs HTTP/1.1
Host: tahoe.workonward.com
Authorization: Bearer thk_live_9tRc4mQx7Lb2sVfE1nKyP6wJdA3zHu8oT5iGq2Xw7Kd4mN3
Accept: application/json

curl -s https://tahoe.workonward.com/api/partner/v1/jobs \
  -H "Authorization: Bearer $TAHOE_API_KEY"

키 형식#

키는 thk_live_ 또는 thk_test_로 시작하고, 그 뒤에 무작위 문자 43자와 4자리 체크섬이 붙습니다. 고정 접두사 thk_ 덕분에 시크릿 스캐너가 실수로 커밋된 키를 찾아낼 수 있습니다. 체크섬이 있어서 잘렸거나 잘못 입력한 키는 바로 거부됩니다.

Tahoe는 시크릿의 단방향 해시만 보관합니다. Tahoe 직원도 키를 다시 읽어 드릴 수 없으므로, 받는 즉시 시크릿 관리 도구에 저장하세요.

test 키와 live 키#

test 키와 live 키는 같은 기본 URL로 같은 워크스페이스를 읽습니다. 샘플 데이터가 담긴 별도 샌드박스가 없으므로 test 키도 실제 레코드를 읽습니다. 접두사는 이름표 역할을 합니다. 로그에서 test 키를 쉽게 알아볼 수 있고, 한 종류의 키만 다른 종류에 영향 없이 모두 폐기할 수 있습니다.

만료#

만든 모든 키는 만료되며, 만들 때 기간을 1일에서 365일 사이로 정합니다. 기본값은 90일입니다. 만료일은 GET /me의 expires_at에서 확인할 수 있습니다. 만료일이 지나면 알 수 없는 키와 똑같은 401을 받으므로, 그 전에 키 교체를 계획하세요.

IP 허용 목록#

키에는 203.0.113.0/24 같은 IP 주소나 CIDR 대역 목록을 지정할 수 있습니다. 다른 주소에서 온 요청은 일반적인 401로 거부됩니다. 허용 목록은 키를 비밀로 지키는 것에 더하는 보호 장치로 쓰세요. 키를 비밀로 지키는 일을 대신하지는 않습니다.

키 교체하기#

정기적으로, 또는 키가 만료되기 전에 시크릿을 바꾸려면 설정의 개발자 탭에서 해당 키의 교체를 누르세요. 이름, 스코프, 워크스페이스, 허용 목록이 같은 새 시크릿이 발급됩니다. 이전 시크릿도 기본 7일 동안 계속 작동하므로 중단 없이 전환할 수 있습니다.

1. 새 시크릿을 배포합니다.
2. 새 시크릿으로 GET /me를 호출해 작동하는지 확인합니다.
3. 겹치는 기간이 끝나면 이전 시크릿은 그대로 만료되게 둡니다.

키 폐기하기#

키를 폐기하면 즉시, 그리고 영구히 사용할 수 없게 됩니다. 되돌릴 방법은 없습니다. 시크릿이 유출되었을 가능성이 있으면 언제든 설정의 개발자 탭에서 해당 키의 폐기를 누르세요. 폐기한 뒤에는 그 키로 보낸 요청이 존재한 적 없는 키와 똑같은 401을 받습니다. 그 키에 속한 웹훅 엔드포인트도 같은 순간 전송을 멈춥니다.

모든 키 문제에 같은 401#

키가 없는 경우, 알 수 없는 키, 폐기되었거나 만료된 키, 형식이 잘못된 키, 허용 목록 밖에서 온 요청은 모두 401과 코드 unauthenticated를 반환합니다. 응답은 이 중 어느 경우인지 알려 주지 않습니다(헤더가 없을 때만 키를 보내라는 안내가 붙습니다).

{
  "detail": {
    "code": "unauthenticated",
    "type": "authentication",
    "message": "Invalid or expired credential.",
    "param": null,
    "doc_url": "https://tahoe.workonward.com/developers/errors#unauthenticated",
    "required_scope": null,
    "retry_after_seconds": null
  }
}

의도한 동작입니다. API가 “폐기됨”과 “존재한 적 없음”을 구분해 알려 주면, 탈취한 키를 가진 사람이 그 키가 아직 유효한지 시험해 볼 수 있습니다. 키가 실패하는 이유를 알 수 없다면 이전 /me 호출에서 받은 expires_at과 설정의 키 목록을 확인한 뒤 문의해 주세요.

스코프#

스코프는 한 종류의 데이터를 읽을 수 있는 권한입니다. 키에는 만들 때 선택한 스코프만 있습니다. 필요한 스코프 없이 엔드포인트를 호출하면 403 insufficient_scope가 반환되며, required_scope에 필요한 스코프가 나옵니다.

{
  "detail": {
    "code": "insufficient_scope",
    "type": "permission",
    "message": "This credential does not carry the contact:read scope.",
    "param": null,
    "doc_url": "https://tahoe.workonward.com/developers/errors#insufficient_scope",
    "required_scope": "contact:read",
    "retry_after_seconds": null
  }
}

필드 하나에 대한 스코프가 없는 것은 오류가 아닙니다. 요청은 성공하고, 해당 필드는 대신 restricted에 나열됩니다. 가려진 필드를 참고하세요.

개인 데이터 일일 한도는 요청 한도와 할당량에서 설명합니다.

키에 줄 수 있는 스코프#

스코프는 세 그룹으로 나뉩니다. 키 만들기 대화상자는 각 스코프의 그룹을 보여 주고, 부여할 수 없는 스코프는 잠가 둡니다.

요금제에 따라 키가 API를 호출할 수 있는 속도와 워크스페이스가 한 달에 보낼 수 있는 요청 수도 정해집니다. 설정에서 내 요금제의 수치를 볼 수 있고, GET /me는 지금까지의 사용량과 함께 수치를 반환합니다. 요청 한도와 할당량을 참고하세요.

일부 스코프를 나눈 이유#

• contact:phone:read는 contact:read와 별도입니다. 전화번호는 Tahoe가 보유한 연락처 중 가장 민감한 정보이기 때문입니다.
• resume:raw_text:read는 resume:read와 별도입니다. 전체 텍스트가 곧 문서 전체이므로, 파일은 보호하고 텍스트는 보호하지 않으면 아무것도 보호하지 못하기 때문입니다.
• applications:internal:read는 applications:read와 별도입니다. 불합격 사유와 점수 근거는 후보자가 읽을 것이라 예상하지 않은 사람이 특정인에 대해 솔직하게 쓴 의견이기 때문입니다.

쓰기를 하는 스코프#

스코프 여덟 개는 데이터를 읽지 않고 바꿉니다. jobs:write, jobs:manage, applications:write, notes:write, scorecards:write, messages:send, lists:write, webhooks:write입니다. 모두 유료 요금제 스코프입니다. 쓰기가 켜져 있으면 키 만들기 대화상자에 나타나며, 이 스코프를 가진 키는 그 스코프를 명시한 엔드포인트만 쓸 수 있습니다.

• jobs:write가 있으면 POST /jobs로 내 시스템에서 온 공고를 만들거나 수정하고 게시할 수 있습니다. 리크루터가 Tahoe에서 만든 공고는 수정하지 않습니다. 채용 공고 레퍼런스를 참고하세요.
• jobs:manage는 워크스페이스의 모든 공고에 닿기 때문에 jobs:write와 별도입니다. 자기 공고를 푸시할 수 있는 키가 리크루터가 쓴 공고까지 마감할 수 있어서는 안 됩니다. 게시, 게시 취소, 마감, 재개를 참고하세요.
• applications:write, notes:write, scorecards:write는 세 스코프로 나뉘어 있어, 메모만 남기는 키가 후보자를 옮기거나 탈락시킬 수 없습니다. 지원서 변경하기와 지원서 만들기를 참고하세요.
• messages:send는 지원한 사람에게 Tahoe의 수신 거부 링크와 함께 이메일을 보내며, 키마다 일일 한도가 있습니다. 메시지를 참고하세요.
• lists:write는 리스트를 만들고 채웁니다. 리스트 만들고 채우기를 참고하세요.
• webhooks:write는 내 웹훅 엔드포인트를 등록합니다. API로 엔드포인트를 등록하는 기능이 켜져 있는 곳에서만 제공됩니다. 엔드포인트 관리하기를 참고하세요.

어떤 쓰기도 아무것도 삭제하지 않습니다. 쓰기 엔드포인트는 모두 POST이며, API에는 PUT, PATCH, DELETE가 없습니다.

쓰기는 누가 한 것으로 기록되는가#

쓰기는 키를 만든 사람이 한 것으로 기록됩니다. 메모, 평가표, 단계 이동, 탈락 처리, 보낸 메시지가 마치 그 사람이 직접 한 것처럼 그 사람의 이름으로 Tahoe에 나타나며, 키가 할 수 있는 일은 그 사람이 할 수 있는 일로 제한됩니다. Tahoe 사용자와 연결할 수 없는 키는 403 write_requires_api_key를 받고 아예 쓸 수 없습니다.

리크루터는 연동 프로그램이 했다는 것을 알 수 있습니다. 지원서, 공고, 리스트의 활동에 종류가 partner_api_로 시작하는 항목이 하나 더 남습니다. 예를 들면 partner_api_stage_move나 partner_api_note_added입니다. 이 항목에는 키 ID와 요청 ID가 들어 있고, 메모나 메시지의 본문은 들어 있지 않습니다. 연동 프로그램마다 키를 하나씩 쓰고 이름을 알아보기 쉽게 붙이세요. 활동을 읽는 사람이 항목 뒤의 연동 프로그램을 찾을 수 있습니다.

요청이 읽는 워크스페이스#

대부분의 키는 워크스페이스 하나에만 속하며, 키가 이미 알고 있으므로 워크스페이스를 따로 지정할 필요가 없습니다. 이런 키는 다른 워크스페이스를 가리킬 수 없습니다. 키가 다루지 않는 워크스페이스를 지정하면 403이 아니라 404가 반환됩니다. 워크스페이스가 존재한다고 확인해 주는 것만으로도 알아서는 안 될 정보를 알려 주게 되기 때문입니다.

둘 이상의 워크스페이스에 접근할 수 있는 키는 모든 호출에서 ?workspace_id=로 대상을 지정해야 합니다.

curl -s "https://tahoe.workonward.com/api/partner/v1/jobs?workspace_id=wsp_4Kd8sPm2Qx7L" \
  -H "Authorization: Bearer $TAHOE_API_KEY"

빠뜨리면 400 workspace_id_required가 반환됩니다. 기본값도 “모든 워크스페이스”도 없으므로, 파라미터 하나를 잊었다고 의도하지 않은 워크스페이스를 읽는 일은 생기지 않습니다.

{
  "detail": {
    "code": "workspace_id_required",
    "type": "invalid_request",
    "message": "This credential can reach multiple workspaces, so workspace_id is required.",
    "param": "workspace_id",
    "doc_url": "https://tahoe.workonward.com/developers/errors#workspace_id_required",
    "required_scope": null,
    "retry_after_seconds": null
  }
}

내 키가 어떤 종류인지 알려면 GET /me를 호출해 workspace_ids와 workspace_id_required를 확인하세요.

Sign in with Tahoe 토큰#

Sign in with Tahoe로 받은 액세스 토큰도 같은 방식으로, 같은 기본 URL에 bearer 토큰으로 보냅니다. 이 토큰은 Tahoe 사용자 한 명으로서 동작합니다. 읽을 수 있는 범위는 앱이 요청한 스코프와 그 사용자가 Tahoe에서 볼 수 있는 것이 겹치는 부분입니다. 연결된 앱의 쓰기가 켜져 있을 때만 쓸 수 있고, 그때는 그 사용자로서 씁니다. 이 토큰으로 개인 데이터를 읽으면 앱뿐 아니라 해당 사용자 이름으로도 기록됩니다.

관련 문서#