모든 Telm API 요청은 tk_live_로 시작하는 API 키로 인증되며, 대시보드 로그인으로는 인증되지 않습니다. 계정에서 키를 만들어 Authorization 헤더에 Bearer 토큰으로 전송하면, 여러분이 관리자인 그룹에서 여러분의 계정을 대신해 동작합니다. 키가 유출되면 대시보드에서 폐기하고 새 키를 발급하세요.
1API 키가 작동하는 방식
Telm REST API는 브라우저 세션을 사용하지 않습니다. 대신 각 요청은 API 키를 담습니다. tk_live_ 접두사로 시작하고 무작위 문자가 뒤따르는 긴 비밀 문자열입니다. 이 키가 여러분의 계정을 식별하고 호출을 인가합니다.
계정에서 키를 생성하며 한 번에 여러 개를 보유할 수 있습니다(예: 스크립트나 서비스마다 하나씩). 전체 비밀은 생성 시점에 단 한 번만 표시됩니다. 그 이후에는 대시보드가 짧은 접두사(tk_live_에 첫 몇 글자)로 키를 목록에 보여주어 알아볼 수 있게 하며, 전체 값은 그 후로 결코 보관되지 않습니다.
- 키는 tk_live_ 뒤에 긴 무작위 문자열이 붙은 형태입니다.
- 키는 대시보드에서 생성하고 관리합니다.
- 전체 비밀은 단 한 번만 표시됩니다. 즉시 복사해 안전한 곳에 보관하세요.
- 키를 비밀번호처럼 다루세요. 그것을 가진 누구든 여러분처럼 API를 호출할 수 있습니다.
2모든 요청에 키 전송하기
Authorization 헤더에 Bearer 스킴으로 키를 전달하세요. 헤더 값은 Bearer라는 단어, 공백 하나, 그리고 여러분의 키입니다. 예: Authorization: Bearer tk_live_your_key_here.
Authorization 헤더를 편하게 설정할 수 없는 클라이언트를 위해, API는 X-API-Key 헤더로 키를 받는 것도 허용합니다. 둘 다 있으면 Authorization 헤더가 우선합니다. 프로덕션에서는 HTTPS가 아닌 어떤 방식의 요청도 허용되지 않습니다.
- 권장: Authorization: Bearer tk_live_... 로 전송.
- 대안: 대신 X-API-Key 헤더로 키를 전송.
- 모든 호출의 기본 URL은 api.telm.com/api/public/v1 입니다.
- 전체 엔드포인트 목록과 스키마는 개발자 페이지를 참고하세요.
3키가 접근할 수 있는 범위
키는 엄격히 여러분의 계정을 대신해 동작합니다. 여러분의 계정이 관리자인 그룹만 읽거나 변경할 수 있습니다. 다른 그룹을 대상으로 하는 요청은 404를 반환하므로, API는 여러분이 관리할 수 없는 그룹이 존재한다는 사실조차 드러내지 않습니다.
접근은 대상 그룹의 요금제에도 좌우됩니다. 스팸 검사 엔드포인트는 일일 할당량 내에서 모든 요금제에 열려 있지만, 전체 API(규칙, 설정, 화이트리스트, 기록, 분석, 배치 검사, 웹훅)는 관련 그룹이 Pro 요금제 이상일 때 사용할 수 있습니다.
- 키는 여러분이 관리자인 그룹만 건드릴 수 있습니다.
- 관리하지 않는 그룹에 대한 요청은 403이 아니라 404를 반환합니다.
- 일일 할당량은 계정 단위로 집계되어 모든 키가 공유합니다.
4키 폐기 및 교체
키가 노출되면 — 저장소에 커밋되거나, 채팅에 붙여넣어지거나, 다른 어떤 방식으로든 유출되면 — 대시보드에서 즉시 폐기하세요. 폐기는 곧바로 적용됩니다. 폐기된 키는 지연 없이 몇 초 안에 작동을 멈춥니다.
일일 할당량은 계정 단위로 공유되므로, 키 하나를 폐기해도 사용량 카운터가 초기화되지는 않습니다. 정기적인 키 교체는 좋은 습관입니다. 새 키를 만들어 서비스에 배포하고 작동을 확인한 뒤 기존 키를 폐기하면 다운타임이 없습니다.
- 대시보드에서 키를 폐기하세요. 거의 즉시 작동을 멈춥니다.
- 무중단 교체를 위해 교체 키를 먼저 만들어 배포한 뒤 기존 키를 폐기하세요.
- 키를 폐기해도 일일 할당량은 초기화되지 않습니다. 그것은 UTC 자정에 초기화됩니다.
5인증 오류
키가 없거나, 형식이 잘못되었거나, 폐기된 경우 401과 함께 기계가 읽을 수 있는 오류 코드와 사람이 읽을 수 있는 메시지를 반환합니다. 요청이 갑자기 401로 실패하기 시작하면, 키가 폐기되지 않았는지, 그리고 Authorization 헤더가 Bearer 다음에 공백 하나 다음에 키의 형태로 정확히 표기되었는지 확인하세요.
관리하지 않는 그룹을 대상으로 하는 유효한 키는 404를 반환합니다. Pro 미만 요금제의 유효한 키가 Pro 전용 엔드포인트를 호출하면 plan_required 코드와 업그레이드 안내와 함께 403을 반환합니다.
- 401 — 키가 없거나, 형식이 잘못되었거나, 폐기됨.
- 404 — 대상 그룹이 존재하지 않거나 여러분이 그 관리자가 아님.
- 403 plan_required — 엔드포인트가 그 그룹에서 Pro 이상을 요구함.