인증 방식 고르기

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

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

기본값은 이렇게 정해요.

• 사람이 앞에 있고 브라우저를 열 수 있으면 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는 인증에, MCP 도구별 scope는 MCP 권한 범위에 있어요.

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

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

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은 생성 응답에만 들어 있으니 서버에서 안전하게 전달하세요. 흐름은 실시간 전사 개요에 있어요.

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/**를 부르면 거절돼요.