메인 콘텐츠로 건너뛰기

API Key

Tiro API는 API Key로 인증해요. 모든 요청의 Authorization 헤더에 API Key를 Bearer 토큰으로 보내세요. 계정 API Key는 사용자 계정에 연결되고, 그 사용자가 현재 접근할 수 있는 모든 워크스페이스에서 사용자와 같은 권한으로 동작해요. 워크스페이스·조직 API Key는 각각 연결된 워크스페이스나 조직을 기준으로 동작해요.
구성원 개인이 키를 발급하지 않고 동의 한 번으로 회사 시스템을 연결하려면 API Key 대신 OAuth 앱을 사용하세요. 등록과 토큰 발급 흐름은 OAuth 앱 연동에 정리해 두었어요.

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이 계속된다면 키가 연결된 워크스페이스와 발급 화면을 먼저 확인하세요.

CLI에서 폴더를 조회할 때

tiro folders list와 tiro folders tree는 OAuth 로그인 또는 계정 API Key가 필요해요. 연동 도구에서 말하는 개인 키는 이 계정 API Key예요. 워크스페이스·조직 시스템 키에 folder:read나 모든 권한을 지정해도 사용자 신원이 생기지는 않아요.
  1. tiro auth status로 현재 인증 source를 확인하세요. TIRO_TOKEN이 있으면 저장된 OAuth 로그인보다 우선해요.
  2. OAuth를 사용하려면 TIRO_TOKEN을 현재 셸에서 제거한 뒤 tiro auth login을 실행하세요. API Key를 사용하려면 TIRO_TOKEN에 계정 API Key를 지정하세요.
  3. tiro wiki workspaces로 대상 GUID를 확인한 뒤 tiro folders list --workspace <guid> 또는 tiro folders tree --workspace <guid>를 실행하세요.
403의 insufficient_scope는 필요한 작업 권한이 없다는 뜻이에요. OAuth는 다시 로그인해 folder:read를 포함하는 권한에 동의하고, API Key는 권한을 수정하거나 새 키로 교체하세요. folder:write도 folder:read를 포함해요. CLI OAuth 요청 URL에 scope가 없어도 서버가 앱·리소스의 허용 범위를 계산해 동의 화면을 제공하므로, URL에 scope를 직접 추가할 필요는 없어요. 401과 User API key is required for folder access가 함께 나오면 사용자 없는 키로 사용자 인증이 필요한 API를 호출한 경우예요. 계정 API Key 또는 OAuth로 바꾸세요. Scope를 늘려서는 해결되지 않아요. 노트가 0건인 경우에는 시스템 API Key가 조회하는 노트 범위를 확인하세요.

권한 범위 (Scope)

Scope는 키가 할 수 있는 작업을 제한해요. 키를 발급할 때 선택하고 나중에도 바꿀 수 있어요.
  • Scope를 지정하지 않으면 해당 키가 접근할 수 있는 리소스 안에서 모든 작업이 허용돼요. 앞으로 추가되는 API도 자동으로 포함돼요. 최소 권한이 필요하면 사용할 scope를 명시하세요. Scope는 열어주는 게 아니라 좁히는 용도예요 — 지정한 scope에 해당하는 API만 호출할 수 있고, 나머지는 403 insufficient_scope로 거부돼요.
  • write scope는 같은 리소스의 read를 포함해요. 이미 발급된 write 키에도 동일하게 적용돼요.
  • Scope는 모든 API Key 종류(사용자·워크스페이스·조직)에 적용돼요.
  • 선택할 수 있는 scope 목록은 GET /v1/api-key-scopes로 조회할 수 있어요.

Scope 목록

본문 수정·초기화와 note_summary:write는 현재 dev 환경에서 검증 중이에요. 운영 환경에서는 아직 사용할 수 없어요. write 권한을 부여해도 해당 환경에서 꺼진 기능이 활성화되지는 않아요.

API별 필요 Scope

Scope를 지정한 키는 아래 표의 scope를 가진 API만 호출할 수 있어요. Scope를 지정하지 않아도 키 종류와 리소스 접근 권한의 제한은 유지돼요.

dev 본문 수정·초기화 API

본문 수정·초기화와 note_summary:write는 현재 dev 환경에서 검증 중이에요. 운영 환경에서는 아직 사용할 수 없어요. write 권한을 부여해도 해당 환경에서 꺼진 기능이 활성화되지는 않아요. 복구 요청은 조회 응답의 editState.etag를 그대로 본문의 etag에 넣어요. undoAvailable과 canReset은 해당 자격증명과 현재 내용에서 가능한 동작을 나타내요. 409이면 다시 조회하고 변경된 내용을 확인한 뒤 사용자가 복구를 다시 선택해야 해요. 새 etag로 Undo를 자동 재시도하지 않아요. 문단 Undo는 지정한 문단·필드의 저장 한 번을 되돌려요. transcript, translated, diarized-transcript, summary를 지원해요. 문단 요약은 복구 가능한 이력이 기록되는 새 저장부터 Undo할 수 있고, 이전 저장은 되돌리지 않아요. editState.canResetByKind는 original, translated, summary의 전체 초기화 가능 여부예요. 각 문단에 표시되지만 해당 노트의 모든 문단을 기준으로 판단해요. POST /v1/external/notes/{noteGuid}/paragraphs:reset에 { "kind": "original", "etag": "조회한 값" }을 보내요. kind는 original, translated, summary 중 하나예요. 모든 문단에서 선택한 종류를 한 번에 초기화해요. original은 일반 원문과 화자별 원문·화자 배정을 함께 초기화하고 번역과 문단 요약은 유지해요. translated는 번역만, summary는 문단 요약만 초기화해요. 초기화한 내용의 이전 Undo는 종료하고 다른 내용과 그 Undo 이력은 유지해요. 원문 초기화는 영향을 받는 이전 화자 변경의 Undo도 막아요. 대상 중 하나라도 초기화할 수 없으면 일부만 처리하지 않고 요청 전체가 실패해요. 기존 문단 하나의 초기화는 동작을 유지해요. 해당 문단의 원문·번역·화자별 문장과 화자 배정을 생성본으로 돌리고 문단 요약은 유지해요. 화자 Undo는 문장 수정을 유지해요. 노트 요약과 문서의 Undo는 각 대상 안에서 최신 저장을 하나씩 되돌려요. 초기화는 요약 또는 문서 전체를 생성본으로 돌리고 이전 Undo를 종료해요. 문서 섹션 초기화는 제공하지 않아요. 기존 수정·초기화 API의 expectedRevision 계약은 유지해요. 나머지 복구 API는 위 표의 경로에 POST하고 { "etag": "조회한 값" }을 보내요. 성공하면 갱신된 복구 상태를 반환하므로 본문은 다시 조회해요.

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는 발급할 때 워크스페이스를 고르지 않아요. 현재 사용자가 접근할 수 있는 워크스페이스를 사용자 신원과 권한으로 다뤄요. 서버 간 연동에 사용자 신원이 필요 없다면 해당 워크스페이스나 조직의 관리 화면에서 시스템 API Key를 발급하세요.
API Key는 안전하게 보관하고 클라이언트 측 코드에 절대 노출하지 마세요. API Key는 서버 측 애플리케이션에서만 사용해야 해요.

API Key 형식

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

인증된 요청 보내기

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

인증 에러

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

보안 모범 사례

환경 변수

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

추가 보안 가이드라인

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