API Key
Tiro API는 API Key로 인증해요. 모든 요청의Authorization 헤더에 API Key를 Bearer 토큰으로 보내세요.
계정 API Key는 사용자 계정에 연결되고, 그 사용자가 현재 접근할 수 있는 모든 워크스페이스에서 사용자와 같은 권한으로 동작해요. 워크스페이스·조직 API Key는 각각 연결된 워크스페이스나 조직을 기준으로 동작해요.
API Key 종류와 권한
Tiro API Key는 호출 주체에 따라 세 가지로 나뉘어요.
워크스페이스 API Key와 조직 API Key는 사용자 없이 동작한다는 점이 같아서, 둘을 묶어 시스템 API Key라고 불러요. 이 문서에서 시스템 API Key라고 하면 두 종류를 함께 가리켜요.
워크스페이스 API Key는 워크스페이스 전체 구성원에게 공유된 폴더에 들어 있는 노트만 다뤄요. 조회뿐 아니라 노트 제목 수정, 공유 링크 생성, 문서 생성처럼 노트를 바꾸는 요청에도 같은 범위가 적용돼요. 개인 폴더에 있는 노트, 일부 구성원에게만 공유한 폴더의 노트, 어느 폴더에도 넣지 않은 노트는 이 범위에서 빠져요. 그 노트까지 다뤄야 한다면 계정 API Key를 발급해 사용하세요.
전환 기간 안내. 이 범위가 적용되기 전에 발급한 워크스페이스 API Key는 당분간 예전처럼 동작하고, 차례로 전환될 예정이에요. 그래서 지금 새로 발급한 키가 기존 키보다 노트를 더 적게 반환할 수 있는데 정상이에요. API Key 종류별 범위와 범위 밖의 노트가 어떤 응답으로 나타나는지는 시스템 API Key가 조회하는 노트 범위에 정리해 두었어요.
워크스페이스 API Key가 아직 워크스페이스에 바인딩되지 않은 상태라면 인증 요청은
401 Unauthorized로 실패할 수 있어요. 키가 올바른 형식인데도 401이 계속된다면 키가 연결된 워크스페이스와 발급 화면을 먼저 확인하세요.권한 범위 (Scope)
Scope는 키가 할 수 있는 작업을 제한해요. 키를 발급할 때 선택하고 나중에도 바꿀 수 있어요.- Scope를 지정하지 않으면 모든 작업이 허용돼요. 앞으로 추가되는 API도 자동으로 포함돼요. 최소 권한이 필요하면 사용할 scope를 명시하세요. Scope는 열어주는 게 아니라 좁히는 용도예요 — 지정한 scope에 해당하는 API만 호출할 수 있고, 나머지는
403 insufficient_scope로 거부돼요. writescope는 같은 리소스의read를 포함해요. 예를 들어note:write만 지정한 키로도note:read가 필요한 조회 API를 호출할 수 있어요.- Scope는 모든 API Key 종류(사용자·워크스페이스·조직)에 적용돼요.
- 선택할 수 있는 scope 목록은
GET /v1/api-key-scopes로 조회할 수 있어요.
Scope 목록
API별 필요 Scope
Scope를 지정한 키는 아래 표의 scope를 가진 API만 호출할 수 있어요. Scope를 지정하지 않은 키는 모든 API를 호출할 수 있어요.API Key 발급
Tiro Platform에서 계정 API Key를 발급받으세요.1
로그인
platform.tiro.ooo/me/api-keys로 이동하세요.
2
계정 API Key 생성
Create New API Key를 클릭하고 이름을 지정한 뒤, 점(.)을 포함한 전체 키를 복사하세요 —
abc123.xR7mK9pL2qW4....3
저장
환경 변수로 저장하세요. 비밀 값은 한 번만 표시되며, 대화 상자를 닫으면 복구할 수 없어요.
API Key 형식
Tiro API Key는 다음 형식을 따라요.abc123.xR7mK9pL2qW4...
인증된 요청 보내기
모든 요청의Authorization 헤더에 API Key를 포함하세요.
인증 에러
인증에 실패하면401 Unauthorized 응답을 받아요.
- Authorization 헤더 누락
- 잘못된 형식의 키 (
{id}.{secret}형식이어야 해요) - 알 수 없는 key id
- 비활성·만료·삭제된 키
보안 모범 사례
환경 변수
환경 변수를 사용해 API Key를 안전하게 보관하세요.추가 보안 가이드라인
- 키를 주기적으로 교체하세요: 사용하지 않는 키는 삭제하고 새 키를 생성하세요
- 환경별로 키를 분리하세요: 개발과 프로덕션에 서로 다른 키를 사용하세요
- 사용량을 모니터링하세요: API Key 사용량을 추적하고 이상이 보이면 교체하세요
- API Key를 절대 로그에 남기지 마세요: 애플리케이션 로그에 키가 나타나지 않도록 하세요
- HTTPS만 사용하세요: 항상 보안 연결로 요청을 보내세요