> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증 방식 고르기

> OAuth, 계정·워크스페이스·조직 API Key, 실시간 전사 streamToken을 누구의 권한으로 동작하는지, 어떤 노트가 보이는지, 언제 쓰는지 기준으로 비교해요.

Tiro API와 MCP에 들어오는 자격 증명은 두 갈래예요. 사람의 권한을 빌리는 자격 증명(OAuth 토큰, 계정 API Key)은 그 사람이 볼 수 있는 노트를 다뤄요. 사람 없이 워크스페이스나 조직에 묶인 자격 증명(워크스페이스 API Key, 조직 API Key)은 새로 발급하면 전체 구성원에게 공유된 폴더의 노트로 제한돼요. 기존 일부 키는 범위가 다를 수 있으니 해당 키를 확인해야 해요.

## 어떤 자격 증명을 써야 하나요?

| 자격 증명 | 누구의 권한으로 | 어떤 노트가 보이나 (API Key는 새로 발급하는 키 기준) | 언제 쓰나 |
| - | - | - | - |
| **OAuth 토큰 (MCP)** | 동의한 사용자 | 그 사용자가 볼 수 있는 노트. 사용자가 속한 모든 워크스페이스가 대상이에요 | Claude, ChatGPT처럼 사용자가 브라우저로 로그인하는 AI 클라이언트 |
| **OAuth 토큰 (REST, [OAuth 앱](https://docs.tiro.ooo/ko/developers/fundamentals/oauth.md))** | 동의한 사용자 | 그 사용자가 볼 수 있는 노트 | 사내 포털이 로그인한 구성원 본인의 노트를 보여줄 때 |
| **계정 API Key** | 키를 만든 사용자 | 그 사용자가 볼 수 있는 노트. 키에 지정한 워크스페이스로 좁힐 수 있어요 | 개인 스크립트, CLI, CI, 브라우저를 열 수 없는 MCP 클라이언트 |
| **워크스페이스 API Key** | 사람 없음 (워크스페이스) | 그 워크스페이스에서 전체 구성원에게 공유된 폴더의 노트 | 워크스페이스 단위 서버 연동, 음성 파일 전사, 실시간 전사 세션 만들기 |
| **조직 API Key** | 사람 없음 (조직) | 조직의 워크스페이스(전체 또는 지정한 워크스페이스)에서 전체 구성원에게 공유된 폴더의 노트 | 조직 단위 배치 작업, 구성원·워크스페이스 관리 자동화 |
| **실시간 전사 `streamToken`** | 세션 하나 | 노트에 접근하지 않아요. 그 전사 세션 하나에만 쓰여요 | 오디오를 보내는 클라이언트가 WebSocket에 붙을 때 |

기본값은 이렇게 정해요.

* 사람이 앞에 있고 브라우저를 열 수 있으면 OAuth를 써요. 사용자가 직접 동의하고, 토큰은 그 사용자 권한을 넘지 않아요.
* 브라우저가 없는 환경(CI, 서버, 헤드리스 에이전트)에서 내 노트를 다루려면 계정 API Key를 써요.
* 특정 사람 없이 팀 공용 자료를 다루는 서버 연동이면 워크스페이스 API Key나 조직 API Key를 써요.

## scope와 노트 범위는 어떻게 다른가요?

scope는 할 수 있는 동작의 종류(`note:read`, `folder:write` 등)를 정해요. 어느 노트와 폴더가 보이는지는 scope가 정하지 않아요. 위 표의 자격 증명 종류가 정해요. 예를 들어 새로 발급한 워크스페이스 API Key는 `note:read` scope가 있어도 개인 폴더의 노트를 볼 수 없어요.

API Key의 scope를 비워 두면 동작 종류의 제한만 없어지고, 자격 증명 종류에 따른 노트 범위는 그대로예요. OAuth에는 빈 scope를 제한 없음으로 다루는 예외가 없어요. 엔드포인트별 필요 scope는 [인증](https://docs.tiro.ooo/ko/developers/fundamentals/authentication.md#api별-필요-scope)에, MCP 도구별 scope는 [MCP 권한 범위](https://docs.tiro.ooo/ko/developers/mcp/setup.md#권한-범위)에 있어요.

## 시스템 API Key는 왜 개인 폴더를 못 보나요?

워크스페이스 API Key와 조직 API Key는 사람의 권한을 빌리지 않는 시스템 API Key예요. 사람의 자격 증명이 아니라 워크스페이스나 조직의 자격 증명이라서, 팀 전체에 공개된 자료인 전체 구성원 공유 폴더의 노트만 다뤄요. 개인 폴더, 일부 구성원에게만 공유한 폴더, 직접 공유받은 노트는 키를 만든 관리자 본인 것이어도 보이지 않아요. 기존에 만든 일부 시스템 API Key는 범위가 다를 수 있으니, 기존 연동의 범위는 그 키를 관리하는 관리자에게 확인하세요.

개인 폴더의 노트까지 다뤄야 하면 그 사용자의 OAuth 토큰이나 계정 API Key를 쓰세요. 자세한 범위는 [시스템 API Key가 조회하는 노트 범위](https://docs.tiro.ooo/ko/developers/fundamentals/system-key-note-scope.md)에 있어요.

## OAuth로 할 수 없는 것은 무엇인가요?

* 조직 관리 API(구성원·워크스페이스·세션), 음성 파일 작업, 실시간 전사 scope는 OAuth로 위임할 수 없어요. API Key로만 호출해요.
* 사용자 없이 토큰을 받는 `client_credentials` 방식은 제공하지 않아요. 서버 간 연동에는 API Key를 쓰세요.
* 실시간 전사 세션은 워크스페이스에 묶인 키로만 만들어요. 워크스페이스에 묶이지 않은 계정 API Key와 조직 API Key는 `403 workspace_bound_key_required`를 받아요.
* Tiro는 OpenID Connect Provider가 아니에요. 다른 서비스의 로그인 수단으로 쓸 수 없고, Tiro OAuth는 Tiro 데이터 접근 권한을 위임하는 데만 써요.

## 실시간 전사는 왜 키를 클라이언트에 주지 않나요?

실시간 전사는 자격 증명을 둘로 나눠요. 고객 서버가 워크스페이스 API Key 또는 워크스페이스에 묶인 계정 API Key로 세션을 만들면 응답에 `wsUrl`과 `streamToken`이 와요. 오디오를 보내는 클라이언트는 `streamToken`만 받아 WebSocket에 붙어요. `streamToken`은 그 세션 하나에만 쓰이므로 API Key 원문이 클라이언트로 가지 않아요. `streamToken`은 생성 응답에만 들어 있으니 서버에서 안전하게 전달하세요. 흐름은 [실시간 전사 개요](https://docs.tiro.ooo/ko/developers/realtime-transcription/overview.md)에 있어요.

## MCP 클라이언트를 직접 만든다면

Tiro MCP 서버(`https://mcp.tiro.ooo/mcp`)는 MCP 인가 규격에 맞춘 OAuth 흐름으로 사용자를 연결해요. 클라이언트는 아래 순서로 서버를 찾고 등록해요.

1. `https://mcp.tiro.ooo/.well-known/oauth-protected-resource/mcp`에서 authorization server(`https://api.tiro.ooo`)를 찾아요.
2. `https://api.tiro.ooo/.well-known/oauth-authorization-server`에서 엔드포인트와 지원 방식을 읽어요.
3. `registration_endpoint`(`POST https://api.tiro.ooo/v1/oauth/register`)에 동적 클라이언트 등록(RFC 7591) 요청을 보내 `client_id`를 받아요.
4. Authorization Code 흐름으로 사용자 동의를 받아요. PKCE는 `S256`만 받아요. `resource=https://mcp.tiro.ooo/mcp`를 함께 보내요.
5. 토큰 엔드포인트에서 code를 토큰으로 바꾸고, MCP 요청에 `Authorization: Bearer <access_token>`을 붙여요.

등록할 때 알아둘 점이에요.

* `redirect_uris`는 `https`, `localhost`·`127.0.0.1`·`[::1]`의 `http`, `cursor` 앱 스킴만 받아요.
* `grant_types`에 `authorization_code`가 있어야 해요. `refresh_token`을 함께 넣은 클라이언트만 refresh token을 받아요.
* `token_endpoint_auth_method`는 `none`, `client_secret_basic`, `client_secret_post`를 받아요.
* `scope`를 생략하면 MCP에서 위임할 수 있는 scope 전체가 클라이언트의 허용 범위가 돼요. 실제 토큰 scope는 사용자가 동의 화면에서 고른 값이에요.
* 동의는 연결할 때마다 다시 받아요.

MCP 토큰과 REST 토큰은 `resource`가 달라 서로 통하지 않아요. MCP용으로 받은 토큰으로 `/v1/external/**`를 부르면 거절돼요.

> [card] [API Key 발급과 scope](https://docs.tiro.ooo/ko/developers/fundamentals/authentication.md)
>
> 키 종류별 발급 위치, scope 목록, 인증 에러를 확인해요.

> [card] [OAuth 앱 연동](https://docs.tiro.ooo/ko/developers/fundamentals/oauth.md)
>
> 사내 시스템이 구성원 동의를 받아 REST API를 부르는 방법이에요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.