본문으로 건너뛰기

파트너 앱용 OAuth

MonoChat 사용자를 위해 일하는 파트너 앱, 자동화 도구 또는 사용자 정의 앱은 API 토큰 대신 OAuth 액세스 토큰으로 사용자 정의 함수 API(POST https://app.monochat.ai/api/<slug>/custom-functions/<path>)를 호출할 수 있습니다. 사용자는 MonoChat 페이지에서 앱을 승인하고, 앱이 접근할 수 있는 조직을 고르며, 프로필 설정의 연결된 앱에서 언제든 취소할 수 있습니다.

API 토큰은 같은 엔드포인트에서 계속 작동합니다. OAuth는 다른 사람을 대신해 동작하는 앱을 위한 방법입니다. 앱은 비밀번호나 API 토큰을 볼 수 없고, 각 사용자가 직접 연결을 끊을 수 있습니다.

앱은 사용자로서 동작합니다

액세스 토큰으로 한 호출은 앱을 승인한 사용자로서, 그 사용자의 역할로 실행됩니다. 조직의 사용자 정의 메서드만 실행하며, 사용자가 상담원인 조직에서만 실행합니다.

클라이언트 받기​

앱용 클라이언트를 MonoChat에 요청하세요. MonoChat은 다음 정보로 등록합니다.

  • 승인 페이지와 연결된 앱에 표시되는 앱 이름
  • 정확히 일치해야 하는 리디렉션 URI: https 주소, 또는 localhost, 127.0.0.1, [::1]의 http(모든 포트)
  • 요청할 수 있는 범위: 이 API에는 custom-functions:run

클라이언트 ID(monochat_rc_로 시작)와 클라이언트 시크릿(monochat_cs_로 시작)을 받습니다. 시크릿은 한 번만 표시되며 MonoChat은 해시만 저장합니다. 시크릿은 서버에 보관하고 브라우저나 모바일 앱에는 절대 두지 마세요.

브라우저나 사용자 컴퓨터에서 실행되는 앱처럼 시크릿을 지킬 수 없는 앱은 MCP 클라이언트처럼 클라이언트 ID 메타데이터 문서의 URL을 클라이언트 ID로 사용할 수 있습니다. 이 경우 시크릿을 보내지 않습니다.

엔드포인트​

https://app.monochat.ai/.well-known/oauth-authorization-server의 인가 서버 메타데이터에 모든 엔드포인트가 나와 있습니다. 화이트 라벨이나 자체 호스팅 설치에서는 해당 설치의 주소를 사용하세요.

설정값
인가 엔드포인트https://app.monochat.ai/oauth/authorize
토큰 엔드포인트https://app.monochat.ai/oauth/token
취소 엔드포인트https://app.monochat.ai/oauth/revoke
리소스https://app.monochat.ai/api/custom-functions
범위custom-functions:run
클라이언트 인증HTTP Basic, 또는 요청 본문의 client_id와 client_secret

리소스 자체의 메타데이터는 https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions에 있습니다.

사용자 연결하기​

MonoChat은 PKCE(S256)를 사용하는 인가 코드 흐름을 씁니다. 사용자는 2단계 인증(이메일 또는 인증 앱)을 설정해 두어야 합니다.

  1. response_type=code, client_id, 등록한 redirect_uri, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, state, code_challenge_method=S256과 함께 code_challenge를 담아 사용자를 인가 엔드포인트로 보냅니다.
  2. 필요하면 사용자가 MonoChat에 로그인합니다. 승인 페이지에 앱 이름과 사용자를 대신해 사용자 정의 메서드 실행이 표시됩니다. 사용자는 앱이 접근할 조직를 고를 수 있고(선택하지 않으면 전체), 6자리 확인 코드를 입력한 뒤 허용를 클릭합니다.
  3. MonoChat은 code, state, iss와 함께 사용자를 redirect_uri로 돌려보냅니다. 사용자가 거부를 클릭하면 대신 error=access_denied를 보냅니다.
  4. 5분 안에 토큰 엔드포인트에서 코드를 교환하세요.
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

응답에는 expires_in초(1시간) 동안 유효한 access_token(monochat_at_로 시작), refresh_token(monochat_rt_로 시작), 부여된 scope가 들어 있습니다.

API 호출하기​

액세스 토큰을 Bearer 토큰으로 보냅니다.

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
상태경우
401토큰을 알 수 없거나 만료 또는 취소되었거나, MCP 서버 같은 다른 리소스용으로 발급되었습니다. WWW-Authenticate 헤더가 리소스 메타데이터를 가리킵니다.
403조직이 사용자가 앱에 허용한 조직이 아니거나, 사용자가 조직에 접근할 수 없거나, 권한 부여에 custom-functions:run이 없습니다.
429한도에 도달했습니다. Retry-After에 있는 초만큼 기다리세요. 호출은 분당으로 계산됩니다. 권한 부여당 120회, 클라이언트당 1,200회이며, 이 엔드포인트에 대한 조직 자체 한도도 적용됩니다.

갱신과 취소​

  • 갱신: 액세스 토큰이 만료되기 전에 grant_type=refresh_token과 refresh_token으로 토큰 엔드포인트를 호출합니다. 갱신할 때마다 새 리프레시 토큰이 반환되니 새 토큰을 사용하세요. 교체된 지 1분이 지나 다시 사용된 리프레시 토큰은 권한 부여를 종료합니다.
  • 만료: 권한 부여는 마지막 갱신 후 90일이 지나거나, 사용자가 연결된 앱에서 취소하거나, 사용자가 비밀번호를 변경 또는 재설정하면 끝납니다. 그 후 사용자는 앱을 다시 승인해야 합니다.
  • 취소: 사용자의 연결을 끊으려면 클라이언트 인증과 함께 액세스 토큰이나 리프레시 토큰을 취소 엔드포인트로 보내세요.
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

같은 사용자를 앱에 다시 연결하면 이전 권한 부여가 대체됩니다.