메인 콘텐츠로 건너뛰기

API 키

Tiro API는 인증에 API 키를 사용해요. 모든 API 요청은 Authorization 헤더에 Bearer token 형식으로 유효한 API 키를 포함해야 해요. 각 키는 하나의 워크스페이스에 귀속돼요. 키는 그 워크스페이스의 리소스 — 노트, 전사, 요약, 폴더 — 에만 닿고, 그 밖으로는 닿지 않아요. 워크스페이스를 먼저 고른 다음 키를 발급하세요.

키 종류와 권한

Tiro API 키는 호출 주체에 따라 두 가지로 나뉘어요. 워크스페이스 시스템 키로 폴더를 읽을 때는 워크스페이스 구성원 전체에게 공유된 폴더만 조회돼요. 개인 폴더나 특정 사용자에게만 공유된 폴더까지 읽어야 하거나, 데이터를 생성·수정·삭제해야 한다면 사용자 키를 발급해 사용하세요.
워크스페이스 시스템 키가 아직 워크스페이스에 바인딩되지 않은 상태라면 인증 요청은 401 Unauthorized로 실패할 수 있어요. 키가 올바른 형식인데도 401이 계속된다면 키가 연결된 워크스페이스와 발급 화면을 먼저 확인하세요.
레거시 개인 키는 곧 사용이 중단돼요. 워크스페이스 도입 이전에 만든 개인 API 키는 2026년 6월 30일부로 작동을 멈춰요. 그 전에 워크스페이스 키를 발급해 교체하세요 — 아래 레거시 개인 키를 참고하세요.

권한 범위 (Scope)

Scope는 키가 어떤 작업을 할 수 있는지를 좁히는 최소 권한 설정이에요. 발급 시 선택하며, 발급 후에도 변경할 수 있어요.
  • Scope를 지정하지 않으면 모든 작업이 허용돼요. Scope는 열어주는 게 아니라 좁히는 용도예요 — 지정한 scope에 해당하는 API만 호출할 수 있고, 나머지는 403 insufficient_scope로 거부돼요.
  • Scope는 모든 키 종류(사용자·워크스페이스·조직)에 적용돼요.
  • 선택할 수 있는 scope 목록은 GET /v1/api-key-scopes로 조회할 수 있어요.

Scope 목록

API별 필요 Scope

Scope를 지정한 키는 아래 표의 scope를 가진 API만 호출할 수 있어요. Scope를 지정하지 않은 키는 모든 API를 호출할 수 있어요.

API 키 발급

Tiro Platform 대시보드에서 API 키를 발급받으세요.
1

로그인

2

워크스페이스 선택

사이드바의 워크스페이스 전환기에서 키가 접근할 데이터의 워크스페이스를 고르세요. 키는 이 워크스페이스에만 한정돼요.
3

키 생성

Create New API Key를 클릭하고 이름을 지정한 뒤, 점(.)을 포함한 전체 키를 복사하세요 — abc123.xR7mK9pL2qW4....
4

저장

환경 변수로 저장하세요. 비밀 값은 한 번만 표시되며, 대화 상자를 닫으면 복구할 수 없어요.
API 키는 안전하게 보관하고 클라이언트 측 코드에 절대 노출하지 마세요. API 키는 서버 측 애플리케이션에서만 사용해야 해요.

API 키 형식

Tiro API 키는 다음 형식을 따라요.
예시: abc123.xR7mK9pL2qW4...
흔한 실수: Key ID(abc123)만 Bearer token으로 쓰지 마세요. 전체 키(abc123.xR7mK9pL2qW4...), 즉 키 생성 시 표시된 전체 문자열을 사용해야 해요.

인증된 요청 보내기

모든 요청의 Authorization 헤더에 API 키를 포함하세요.

인증 에러

인증에 실패하면 401 Unauthorized 응답을 받아요. 흔한 원인은 다음과 같아요.
  • Authorization 헤더 누락
  • 잘못된 형식의 키 ({id}.{secret} 형식이어야 해요)
  • 알 수 없는 key id
  • 비활성·만료·삭제된 키

레거시 개인 키 (지원 중단)

워크스페이스 도입 이전에는 개인 API 키가 워크스페이스가 아니라 계정에 묶여 있었어요. 이 개인 키는 이제 지원이 중단돼요. 키는 이제 워크스페이스 키로 들어와요 — 각 팀이 하나의 워크스페이스에 대응해요. 워크스페이스 키가 개인 키와 팀 키를 모두 대체해요.
레거시 개인 키는 2026년 6월 30일부로 작동을 멈춰요. 그 이후 레거시 개인 키로 보낸 요청은 401 Unauthorized를 반환해요. 중단 없이 쓰려면 그 전에 마이그레이션하세요.
형식이 같으므로 마이그레이션은 한 줄 교체면 돼요 — 코드를 다시 쓸 필요 없어요.

3단계로 마이그레이션하기

1

워크스페이스 키 발급

대시보드에서 통합이 사용하는 노트가 들어 있는 워크스페이스를 선택한 뒤 키를 발급하세요.
2

비밀 값 교체

TIRO_API_KEY 환경 변수 값을 새 키로 바꾸세요. 다른 코드 변경은 필요 없어요.
3

레거시 키 폐기

트래픽이 새 키로 도는 게 확인되면, 대시보드의 Legacy personal keys 섹션에서 레거시 키를 삭제하세요.
레거시 키는 계정의 모든 노트에 닿았지만, 워크스페이스 키는 하나의 워크스페이스에만 닿아요. 데이터가 여러 워크스페이스에 걸쳐 있다면 워크스페이스마다 키를 하나씩 발급하세요.

보안 모범 사례

환경 변수

환경 변수를 사용해 API 키를 안전하게 보관하세요.

추가 보안 가이드라인

  • 키를 주기적으로 교체하세요: 사용하지 않는 키는 삭제하고 새 키를 생성하세요
  • 환경별로 키를 분리하세요: 개발과 프로덕션에 서로 다른 키를 사용하세요
  • 사용량을 모니터링하세요: API 키 사용량을 추적하고 이상이 보이면 교체하세요
  • API 키를 절대 로그에 남기지 마세요: 애플리케이션 로그에 키가 나타나지 않도록 하세요
  • HTTPS만 사용하세요: 항상 보안 연결로 요청을 보내세요