모두싸인 OAuth 2.0 가이드

모두싸인은 OAuth 2.0 Authorization Code Grant 방식을 통해 외부 애플리케이션이 사용자를 대신하여 모두싸인 리소스에 안전하게 접근할 수 있도록 지원합니다. 인증 구현은 RFC 6749 최종 스펙을 기반으로 합니다.

💡

OAuth를 사용해야 하는 경우

외부 서비스에서 모두싸인 기능을 제공하고 싶을 때 사용합니다. 사용자가 권한을 허가하면, 허가된 범위 내에서 외부 서비스가 사용자를 대신해 모두싸인 API를 호출할 수 있습니다.

시작 전 준비 사항

OAuth 연동을 시작하기 전에 아래 사항을 확인하세요.

• 모두싸인 계정 보유
• 고객센터를 통한 OAuth 애플리케이션 등록 (고객센터 바로가기)
• 애플리케이션 등록 후 발급된 clientId 및 clientSecret

❗️

clientSecret은 애플리케이션의 패스워드 역할을 합니다. 절대 외부에 노출하지 마세요. 반드시 서버사이드에서만 처리해야 하며, 브라우저나 모바일 앱에서 직접 사용하는 것은 심각한 보안 취약점이 됩니다.

전체 인증 흐름

모두싸인 OAuth는 아래 4단계로 구성됩니다.

1단계: 애플리케이션 등록

📘

현재 애플리케이션 등록은 모두싸인 고객센터를 통해서만 신청 가능합니다. OAuth 기능 이용에 대한 문의도 동일하게 고객센터로 연락해 주세요.

애플리케이션 등록 시 아래 정보가 필요합니다.

등록이 완료되면 아래 두 가지 자격증명이 발급됩니다.

2단계: 인가 요청 및 Authorization Code 발급

사용자를 아래 인가 요청 페이지로 리디렉션하여 모두싸인 계정 연동 동의를 받습니다.

인가 요청 URL

GET https://app.modusign.co.kr/oauth/authorize

요청 파라미터

요청 URL 예시

https://app.modusign.co.kr/oauth/authorize?response_type=code&client_id=01FQE43XG5KAAA3ZKL4DFQ1S66&state=8759367&redirect_uri=https%3A%2F%2Fsite.com%2Fcallback

사용자가 모두싸인에 로그인되어 있지 않으면 로그인 페이지로 이동 후 인가 요청 페이지로 자동 전환됩니다.

인가 결과

https://site.com/callback?code=94228db4tt12&state=8759367

📘

로그아웃이 필요한 경우

다른 계정으로 재연결하거나 세션을 초기화할 때는 아래 URL을 호출하여 모두싸인 계정을 로그아웃 처리하세요.

https://app.modusign.co.kr/signout?redirectTo=${encodeURIComponent('https://modusign.co.kr')}

redirectTo를 지정하지 않으면 모두싸인 로그인 페이지로 이동합니다.

3단계: Access Token 발급

Authorization Code를 사용하여 실제 API 호출에 사용할 access_token을 발급받습니다.

엔드포인트

POST https://api.modusign.co.kr/oauth/token

요청 파라미터

요청 예시

curl --request POST \
     --url https://api.modusign.co.kr/oauth/token \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
       "grant_type": "authorization_code",
       "client_id": "CLIENT-ID",
       "client_secret": "CLIENT-SECRET",
       "code": "AUTHORIZATION-CODE",
       "redirect_uri": "https://site.com/callback"
     }'

응답 예시

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 1800
}

응답 필드

📘

Refresh Token 갱신 정책

Refresh Token은 60일 간 유효합니다. 발급 후 30일이 경과한 시점에 access_token을 재발급하면 새로운 Refresh Token이 함께 반환됩니다. 새 Refresh Token을 수신할 때마다 안전한 저장소에 즉시 갱신하여 저장하세요.

4단계: Access Token으로 API 호출

발급받은 access_token을 Authorization 헤더에 Bearer 타입으로 설정하여 API를 호출합니다.

Authorization: Bearer {access_token}

문서 목록 조회 예시

curl --request GET \
     --url 'https://api.modusign.co.kr/documents?offset=0&limit=10' \
     --header 'Authorization: Bearer {access_token}'

Access Token 갱신 (Refresh)

access_token은 30분 후 만료됩니다. 만료된 경우 저장해 둔 refresh_token으로 새 토큰을 발급받으세요.

엔드포인트

POST https://api.modusign.co.kr/oauth/token

요청 파라미터

요청 예시

curl --request POST \
     --url https://api.modusign.co.kr/oauth/token \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
       "grant_type": "refresh_token",
       "client_id": "CLIENT-ID",
       "client_secret": "CLIENT-SECRET",
       "refresh_token": "REFRESH-TOKEN"
     }'

📘

응답의 refresh_token 필드는 기존 Refresh Token의 잔여 유효기간이 30일 미만일 때만 새 값으로 반환됩니다. 새 값이 포함된 경우 반드시 저장소를 즉시 갱신하세요.

토큰 삭제 (Revoke)

사용자가 연동을 해제하거나 보안 이슈가 발생한 경우, 토큰 발급 취소 API를 통해 즉시 토큰을 무효화하세요.

엔드포인트

POST https://api.modusign.co.kr/oauth/token/revoke

요청 파라미터

요청 예시

curl --request POST \
     --url https://api.modusign.co.kr/oauth/token/revoke \
     --header 'Content-Type: application/json' \
     --data '{
       "client_id": "CLIENT-ID",
       "client_secret": "CLIENT-SECRET",
       "token": "ACCESS-OR-REFRESH-TOKEN"
     }'

성공 시 HTTP 204 No Content 가 반환됩니다. 응답 바디는 없습니다.

❗️

사용자가 연동을 해제할 때 access_token과 refresh_token 모두 revoke 처리하세요. refresh_token이 탈취된 경우에도 즉시 revoke하여 추가 피해를 방지하세요.

토큰 유효 기간 요약

관련 API 레퍼런스

• 토큰 발급 및 갱신 API
• 토큰 발급 취소 API
• 문서 리스트 조회 API