전자서명 API 인증키(API Key)·OAuth 발급받는 법

Q: test 키와 live 키는 어떻게 다른가요?

sk_test_는 샌드박스 전용이라 실발송·실과금·실알림톡이 일어나지 않습니다. 흐름 검증이 끝나면 sk_live_ 키로 교체해 운영에 사용하세요.

Q: API Key를 잃어버리면 다시 볼 수 있나요?

키 전체 값은 생성 직후 한 번만 표시되며 이후 다시 확인할 수 없습니다. 분실 시에는 대시보드에서 해당 키를 회수(재발급)하고 새 키로 교체하는 것이 안전합니다.

Q: OAuth와 API Key를 함께 써도 되나요?

네. 서버 자동화에는 API Key, Claude 같은 대화형 도구에는 OAuth 2.1을 쓰는 식으로 나눠 구성하는 것이 일반적입니다. 두 방식 모두 동일한 백엔드를 사용합니다.

싸인딜 전자서명 API 인증은 두 갈래입니다. 서버-투-서버 자동화에는 API Key(Bearer), Claude 같은 대화형 MCP 클라이언트에는 OAuth 2.1(PKCE) 를 쓰며, 둘 다 싸인딜 대시보드에서 발급·관리합니다. (개발자 연동은 현재 베타 단계로 범위가 순차 확장됩니다.)

API Key와 OAuth 2.1 중 무엇을 써야 하나요?

백엔드 자동화·플랫폼 연동에는 API Key, 사용자가 대화로 호출하는 MCP 도구에는 OAuth 2.1이 기본입니다. API Key는 `Authorization: Bearer sk_live_...` 헤더 하나로 끝나는 가장 단순한 방식이고, OAuth 2.1은 사용자가 로그인 화면에서 권한을 승인해 토큰을 받는 방식입니다. 두 방식 모두 발급된 토큰은 조직(tenant) 단위로 스코핑되며, 권한도 필요한 최소 범위(scope)만 부여하는 것이 안전합니다. 그래야 키 하나가 다른 계정의 데이터에 접근하는 일을 막을 수 있습니다.

| 구분 | API Key | OAuth 2.1 |

|---|---|---|

| 용도 | 백엔드·서버 자동화 | MCP·대화형 클라이언트 |

| 인증 헤더 | `Bearer sk_live_…` | `Bearer <access_token>` |

| 발급 | 대시보드에서 직접 생성 | 클라이언트 등록 후 인가 흐름 |

API Key는 어떻게 발급받나요?

API Key는 싸인딜 대시보드의 개발자 설정에서 환경을 고른 뒤 클릭 한 번으로 생성합니다. 순서는 다음과 같습니다.

1. 환경 선택: 먼저 `sk_test_…`(샌드박스)로 시작하세요. 실발송·실결제 없이 흐름만 검증됩니다. 운영 전환 시 `sk_live_…`를 발급합니다.

2. 키 생성·복사: 키 전체 값은 생성 직후 한 번만 표시되므로 그때 안전하게 복사합니다.

3. 서버에 보관: 키는 환경변수로 저장하고, 베이스 URL `https://api.signdeal.kr/v1` 에 `Authorization: Bearer ...` 헤더로 호출합니다. REST 경로는 레이트리밋과 스코프로 보호되니, 용도별로 키를 나눠 발급해 두면 사고 시 영향 범위를 줄일 수 있습니다.

OAuth 클라이언트는 어떻게 등록하고 토큰을 받나요?

OAuth는 클라이언트를 등록해 식별자를 받은 뒤 인가(authorize) → 코드 교환(token) 순서로 access token을 발급받습니다. MCP 표준에 맞춰 PKCE(S256)를 사용하며, 토큰의 `aud`(대상)는 `https://mcp.signdeal.kr/mcp` 로 검증됩니다. 다행히 Claude 같은 MCP 클라이언트는 서버에 연결할 때 브라우저 인가 창을 띄워 이 과정을 대부분 자동으로 처리합니다. MCP가 아닌 직접 구현이라면 등록 시 redirect_uri를 정확히 일치시키고, CSRF 방지를 위해 state 값을 함께 검증해야 합니다. OAuth 2.1 동적 등록은 현재 베타로 순차 적용 중이라, 빠르게 붙이려면 API Key가 더 간단할 수 있습니다.

키 보안·회수·만료는 어떻게 다루나요?

노출이 의심되면 대시보드에서 해당 키를 즉시 회수(재발급)하고 새 키로 교체하는 것이 원칙입니다. API Key는 비밀값이므로 로그·응답·공개 저장소에 남기지 말고 서버 환경변수로만 보관하세요. OAuth access token은 만료 시간(`exp`)이 있어 일정 시간 뒤 무효가 되며 refresh token으로 갱신합니다. 401(unauthorized)이 나오면 토큰이 없거나 만료·무효인 경우이니 갱신 후 재시도하면 됩니다.

AI(MCP)로 쓸 때 vs API로 쓸 때

AI(MCP)로: Claude·Codex 등에 싸인딜 MCP 서버(`https://mcp.signdeal.kr/mcp`)를 연결하면 OAuth 2.1으로 인증되고, "차용증 써서 보내줘" 같은 대화로 도구를 호출합니다. 발송 계열은 dry-run 미리보기 → 승인 토큰 2단계가 서버단에서 강제됩니다.
API로: 백엔드에서 `Bearer sk_live_...` 헤더로 REST를 직접 호출합니다. 자동화·대량 연동에 적합하며, 동일하게 dry-run → confirmation_token 흐름을 따릅니다.

자주 묻는 질문 (FAQ)

Q. test 키와 live 키는 어떻게 다른가요?

`sk_test_`는 샌드박스 전용이라 실발송·실과금·실알림톡이 일어나지 않습니다. 검증이 끝나면 `sk_live_`로 교체하세요.

Q. API Key를 잃어버리면 다시 볼 수 있나요?

전체 값은 생성 직후 한 번만 표시됩니다. 분실 시 다시 확인할 수 없으므로, 대시보드에서 회수하고 새로 발급받는 것이 안전합니다.

Q. OAuth와 API Key를 함께 써도 되나요?

네. 서버 자동화는 API Key, 대화형 도구는 OAuth로 나눠 쓰는 구성이 일반적이며, 둘 다 같은 백엔드를 사용합니다.

---

> 이 글은 일반 정보 제공용이며 법률 자문이 아닙니다. 전자서명법·전자문서법의 일반 원칙을 참고용으로 정리한 것으로, 인증 키 사용 자체가 개별 계약의 법적 효력을 100% 보장하지는 않습니다. 개별 사안은 전문가와 상담하세요. 싸인딜 개발자 연동은 베타 단계로 일부 기능과 발급 방식은 변동될 수 있습니다.

더 알아보기