Skip to main content

API 키

Tiro API는 API 키로 인증해요. 모든 요청의 Authorization 헤더에 API 키를 Bearer 토큰으로 보내세요. 각 키는 하나의 워크스페이스에 속하며 그 워크스페이스의 노트, 전사, 요약, 폴더에만 접근해요. 워크스페이스를 고른 뒤 키를 발급하세요.

키 종류와 권한

Tiro API 키는 호출 주체에 따라 두 가지로 나뉘어요. 워크스페이스 시스템 키는 워크스페이스 전체 구성원에게 공유된 폴더에 들어 있는 노트만 조회해요. 개인 폴더에 있는 노트, 일부 구성원에게만 공유한 폴더의 노트, 어느 폴더에도 넣지 않은 노트는 조회 범위에서 빠져요. 그 노트까지 읽어야 하거나, Voice File Job 생명주기 외의 데이터를 생성·수정·삭제해야 한다면 사용자 키를 발급해 사용하세요.
전환 기간 안내. 이 범위가 적용되기 전에 발급한 워크스페이스 시스템 키는 당분간 예전처럼 동작하고, 차례로 전환될 예정이에요. 그래서 지금 새로 발급한 키가 기존 키보다 노트를 더 적게 반환할 수 있는데 정상이에요. 키 종류별 조회 범위와 조회되지 않는 노트가 어떤 응답으로 나타나는지는 시스템 키가 조회하는 노트 범위에 정리해 두었어요.
워크스페이스 시스템 키가 아직 워크스페이스에 바인딩되지 않은 상태라면 인증 요청은 401 Unauthorized로 실패할 수 있어요. 키가 올바른 형식인데도 401이 계속된다면 키가 연결된 워크스페이스와 발급 화면을 먼저 확인하세요.
레거시 개인 키는 곧 사용이 중단돼요. 워크스페이스 도입 이전에 만든 개인 API 키는 2026년 6월 30일부로 작동을 멈춰요. 그 전에 워크스페이스 키를 발급해 교체하세요 — 아래 레거시 개인 키를 참고하세요.

권한 범위 (Scope)

Scope는 키가 할 수 있는 작업을 제한해요. 키를 발급할 때 선택하고 나중에도 바꿀 수 있어요.
  • Scope를 지정하지 않으면 모든 작업이 허용돼요. 앞으로 추가되는 API도 자동으로 포함돼요. 최소 권한이 필요하면 사용할 scope를 명시하세요. Scope는 열어주는 게 아니라 좁히는 용도예요 — 지정한 scope에 해당하는 API만 호출할 수 있고, 나머지는 403 insufficient_scope로 거부돼요.
  • write scope는 같은 리소스의 read를 포함해요. 예를 들어 note:write만 지정한 키로도 note:read가 필요한 조회 API를 호출할 수 있어요.
  • 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만 사용하세요: 항상 보안 연결로 요청을 보내세요