API 문서

고급 인증 패턴 — OAuth 2.0, JWT, 키 로테이션

엔터프라이즈 환경에서 Smart Money API를 통합하기 위한 정교한 인증 메커니즘을 마스터하세요. OAuth 2.0 플로우, JWT 토큰 패턴, 안전한 키 로테이션 및 다중 인증 구현을 배웁니다.

2026년 3월 21일 발행 • 18분 읽기 • 고급

인증 개요

Smart Money API는 다양한 애플리케이션 아키텍처, 보안 요구 사항 및 조직 정책을 수용하도록 설계된 여러 인증 방법을 지원합니다. 이러한 패턴을 이해하면 통합이 안전하고 성능이 우수하도록 보장할 수 있습니다.

Smart Money API의 인증은 세 가지 주요 계층에서 작동합니다:

  • API 키 — 개발 및 간단한 통합을 위한 간단한 Bearer 토큰 인증
  • JWT 토큰 — 분산 시스템 및 마이크로서비스용 상태 비저장 암호화 토큰
  • OAuth 2.0 — 타사 통합 및 SaaS 애플리케이션을 위한 위임된 권한 부여 프레임워크

보안 원칙: 클라이언트 측 코드, 로그, 버전 관리 또는 오류 메시지에서 인증 자격 증명을 노출하지 마십시오. 일정에 따라 자격 증명을 로테이션하고 손상 시 즉시 로테이션하십시오.

각 방법에는 고유한 장점이 있습니다. API 키는 자격 증명 저장소가 제어되는 백엔드 간 통신에 가장 적합합니다. JWT 토큰은 공유 상태가 없는 분산 아키텍처에서 뛰어납니다. OAuth 2.0은 타사 애플리케이션을 위한 사용자 위임 액세스를 제공합니다.

API 키 인증

API 키는 가장 간단한 인증 메커니즘입니다. 이는 귀하의 계정에 대해 생성된 임의의 문자열로, Smart Money API에 귀하의 애플리케이션을 식별합니다. 모든 요청은 헤더 또는 쿼리 매개변수로 귀하의 API 키를 포함해야 합니다.

헤더 기반 API 키

권장 접근 방식은 Bearer 스키마를 사용하여 Authorization 헤더에 API 키를 전달하는 것입니다:

curl 예제
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"

쿼리 매개변수 API 키

WebSocket 연결 또는 헤더를 수정할 수 없는 경우 쿼리 매개변수로 API 키를 전달하십시오:

WebSocket 연결
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// 인증된 WebSocket 스트림 설정

API 키 특성

속성 설명
형식 sk_test_ 또는 sk_live_ 접두사가 붙은 128자리 16진수 문자열
범위 생성한 계정의 모든 권한 상속
만료 자동으로 만료되지 않음; 수동으로 로테이션해야 함
로테이션 새 키 생성, 트래픽 마이그레이션, 이전 키 비활성화
속도 제한 동일한 키를 사용하는 모든 요청에서 공유

API 키 보안 사례

  • 환경 변수 — .env 파일에 키 저장 (버전 관리에 커밋되지 않음) 및 런타임에 로드
  • 볼트 시스템 — 프로덕션 환경에서는 HashiCorp Vault, AWS Secrets Manager 또는 Azure Key Vault 사용
  • 분리된 키 — 테스트 키와 라이브 키를 분리하여 관리하고 테스트 키는 자주 교체하세요
  • 최소 권한 범위 — 가능한 경우 각 통합에 대해 별도의 키 생성
  • 감사 로깅 — 모든 API 키 생성 및 사용 이벤트 로깅
30초 안에 API 키 발급받기

준비가 되셨나요? 무료 API 키(일일 100회 호출, 카드 불필요)를 받고 실시간 고래, 펀딩 및 온체인 데이터를 가져오세요.

API 키 발급받기 →

Bearer 토큰 패턴

Bearer 토큰은 간단한 API 키 개념에 컨텍스트, 만료 및 갱신 메커니즘을 추가합니다. 프로그램 방식의 자격 증명 관리가 필요한 애플리케이션에 이상적입니다.

Bearer 토큰 획득

24시간 동안 유효한 Bearer 토큰을 얻기 위해 API 키와 시크릿을 교환하세요:

GET /auth/token
curl -X POST "https://api.smartmoneyapi.com/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_1234567890",
"api_secret": "secret_abc123xyz"
}'

토큰 응답 형식

이 엔드포인트는 메타데이터가 포함된 Bearer 토큰을 반환합니다:

응답
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}

Bearer 토큰 사용

모든 후속 요청에 Authorization 헤더에 토큰을 포함하세요:

인증된 요청
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

토큰 갱신 흐름

토큰이 만료되기 전에 API 시크릿 없이 새 토큰을 얻기 위해 리프레시 토큰을 사용하세요:

POST /auth/refresh
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'

OAuth 2.0 구현

OAuth 2.0을 사용하면 사용자가 자격 증명을 공유하지 않고도 애플리케이션에 Smart Money API 계정 액세스 권한을 부여할 수 있습니다. SaaS 플랫폼, 타사 통합 및 멀티테넌트 애플리케이션에 필수적입니다.

OAuth 2.0 인증 코드 흐름

웹 애플리케이션을 위한 표준 흐름:

  1. 사용자 로그인 시작 — 사용자가 "Smart Money API로 연결" 클릭
  2. 인증 서버로 리디렉션 — 앱이 사용자를 Smart Money의 인증 엔드포인트로 리디렉션
  3. 사용자 권한 부여 — 사용자가 요청된 범위를 검토하고 액세스 권한 부여
  4. 인증 코드 반환 — 사용자가 인증 코드와 함께 리디렉션됨
  5. 토큰 교환 코드 — 백엔드가 코드를 액세스 토큰으로 교환(코드는 프론트엔드에 노출되지 않음)
  6. 토큰 저장 — 리프레시 토큰을 안전하게 저장하고, API 호출에는 액세스 토큰을 사용하세요.

1단계: 사용자를 인증 엔드포인트로 리디렉션

프론트엔드 리디렉션
// 사용자를 리디렉션할 URL
const authUrl = new URL('https://api.smartmoneyapi.com/oauth/authorize');
authUrl.searchParams.append('client_id', 'your_client_id');
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'whales derivatives onchain');
authUrl.searchParams.append('state', generateRandomState());
window.location.href = authUrl.toString();

2단계: 콜백 처리 및 코드 교환

백엔드 코드 교환
// 백엔드에서 /callback 경로 처리
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// state 매개변수 확인
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// 코드를 토큰으로 교환
const tokenResponse = await fetch('https://api.smartmoneyapi.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code: code,
client_id: process.env.OAUTH_CLIENT_ID,
client_secret: process.env.OAUTH_CLIENT_SECRET,
redirect_uri: 'https://yourapp.com/callback'
})
});
const tokens = await tokenResponse.json();
// 토큰을 안전하게 저장

OAuth 스코프

애플리케이션에 필요한 스코프만 요청하세요. Smart Money API는 다음과 같은 스코프를 정의합니다:

스코프 설명
whales 고래 지갑 추적 및 축적 지표 접근
derivatives 선물, 영구 스왑 및 펀딩 비율 데이터 접근
onchain 온체인 트랜잭션 흐름 및 분석 접근
alerts 웹훅 알림 생성 및 관리
offline 오프라인에서 새로운 액세스 토큰을 얻기 위한 리프레시 토큰 접근

JWT 토큰 관리

JWT(JSON Web Tokens)는 상태 비저장 인증을 제공합니다—서버가 세션 데이터를 저장할 필요가 없습니다. Smart Money API는 토큰 서명을 위해 RS256(RSA Signature with SHA-256)을 사용하여 API에 접근하지 않고도 검증이 가능합니다.

JWT 구조

JWT 토큰은 점으로 구분된 세 부분으로 구성됩니다:

JWT 형식
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE

JWT 헤더

헤더는 알고리즘과 토큰 유형을 식별합니다:

디코딩된 헤더
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}

JWT 페이로드 클레임

페이로드는 클레임(사용자/앱에 대한 설명)을 포함합니다:

디코딩된 페이로드
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}

JWT 서명 검증

Smart Money의 공개 키를 다운로드하고 토큰을 수락하기 전에 검증하세요:

Node.js 검증
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Smart Money API에서 공개 키 가져오기
const publicKey = fs.readFileSync('smartmoney-public.pem');
// 토큰 검증
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// 토큰이 유효함, 디코딩된 클레임 사용
} catch (err) {
// 토큰이 유효하지 않거나 만료됨
}

키 회전 전략

정기적인 키 회전은 보안을 유지하는 데 중요합니다. 완벽한 보안 관행을 유지하더라도 키가 손상될 수 있다고 가정하고 체계적인 회전을 구현하세요.

회전 빈도

Smart Money는 키 유형 및 사용에 따라 다양한 회전 일정을 권장합니다:

키 유형 권장 회전 최소 회전
테스트 API 키 월간 분기별
프로덕션 API 키 분기별 연간
OAuth 리프레시 토큰 자동(90일 후) 수동(180일 후)
서비스 계정 키 반년마다 연간

다운타임 없는 회전 프로세스

서비스 중단 없이 키를 회전하세요:

  1. 새 키 생성 — 대시보드 또는 API를 통해 새 API 키 생성
  2. 새 키 배포 — 스테이징에서 애플리케이션 비밀 업데이트, 철저히 테스트
  3. 점진적 롤아웃 — 서버의 10%에 배포, 오류 모니터링
  4. 전면 롤아웃 — 남은 서버에 배포
  5. 트래픽 확인 — 모든 요청이 새 키를 사용하는지 확인
  6. 이전 키 비활성화 — 이전 키를 비활성화로 표시하지만 즉시 삭제하지 않음
  7. 이전 키 삭제 — 48시간 동안 오류가 없으면 영구 삭제

긴급 키 교체

키가 유출되었다고 의심되는 경우:

긴급 교체
// 즉각적인 조치: 유출된 키 비활성화
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// 즉시 대체 키 생성
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "긴급 대체 키"
}'

Kubernetes에서 자동화된 교체

Kubernetes Secrets와 연산자를 사용하여 자동 교체:

키 교체를 위한 CronJob
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # 매주 일요일
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest

다중 인증 (MFA)

프로덕션 데이터에 접근하는 계정의 경우, MFA는 자격 증명 외에 두 번째 요소를 요구하여 추가 보안 계층을 제공합니다.

지원되는 MFA 방법

  • TOTP (시간 기반 일회용 비밀번호) — Google Authenticator, Authy와 같은 앱
  • WebAuthn/FIDO2 — 하드웨어 보안 키, 생체 인식
  • SMS 일회용 코드 — 덜 안전하지만 보편적으로 지원됨
  • 이메일 확인 — 등록된 이메일로 전송된 확인 코드

계정 접근을 위한 TOTP 활성화

MFA 활성화
// 1단계: MFA 설정 요청
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// 응답에 QR 코드 URL 포함
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}

API 작업 중 MFA

일부 작업은 인증 후에도 MFA 확인을 요구할 수 있습니다:

MFA 챌린지
// 민감한 작업 시도 (키 교체)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// 응답: MFA 필요
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// TOTP 코드로 재시도
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"

보안 모범 사례

인증은 구현만큼 강력합니다. 보안을 유지하기 위해 다음 사항을 준수하세요:

비밀 관리

  • 비밀을 버전 관리에 절대 커밋하지 마세요 — .gitignore와 함께 .env 파일 사용
  • 환경 변수 사용 — 안전한 비밀 관리 시스템에서 로드
  • 저장소 스캔 — TruffleHog, detect-secrets와 같은 도구를 사용하여 노출된 키 찾기
  • 접근 로그 감사 — 누가 언제 비밀에 접근했는지 모니터링

전송 보안

  • 항상 HTTPS 사용 — 암호화되지 않은 연결로 자격 증명을 절대 전송하지 마세요
  • SSL 인증서 확인 — 프로덕션 환경에서 인증서 검증을 비활성화하지 마세요
  • 인증서 고정 사용 — 모바일 앱의 경우 MITM 공격 방지
  • TLS 1.2+ 강제 — 이전 프로토콜 비활성화

자격 증명 처리

  • 비밀 해시 — bcrypt 또는 Argon2 해시 저장, 평문 절대 금지
  • 수명 최소화 — 필요한 동안만 메모리에 자격 증명 보관
  • 민감한 데이터 지우기 — 사용 후 명시적으로 자격 증명 덮어쓰기
  • 안전한 라이브러리 사용 — 암호화를 직접 구현하지 마세요

로깅 및 모니터링

  • 자격 증명을 절대 로깅하지 마세요 — 로그에서 키를 가리고 로그 마스킹 사용
  • 인증 이벤트 로깅 — 성공 및 실패한 로그인 시도 추적
  • 이상 징후 모니터링 — 비정상적인 접근 패턴에 대해 알림
  • 키 사용 감사 — 어떤 키가 어떤 데이터에 접근했는지 추적

엔터프라이즈 인증 패턴

대규모 조직은 종종 추가 보안 제어 및 규정 준수 기능이 필요합니다.

SAML 2.0 통합

엔터프라이즈 고객을 위해 Smart Money API는 조직의 ID 공급자(Okta, Azure AD 등)와의 SAML 2.0 통합을 지원합니다:

  • 싱글 사인온 (SSO) — 사용자가 회사 IdP를 통해 인증
  • 자동 프로비저닝 — 그룹 멤버십에 기반한 계정 생성/비활성화
  • 강제 — 모든 사용자 접근에 SAML 요구

IP 화이트리스트

특정 IP 주소 또는 CIDR 범위로 API 접근 제한:

IP 화이트리스트 관리
// IP를 화이트리스트에 추가
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "프로덕션 서버"
}'

감사 로깅 및 규정 준수

엔터프라이즈 플랜은 규정 준수를 위한 포괄적인 감사 로그를 포함합니다:

이벤트 로그된 데이터
인증 사용자, 타임스탬프, 성공/실패, IP, MFA 상태
키 작업 키 ID, 작업, 시작자, 타임스탬프
계정 변경 변경된 내용, 변경한 사람, 타임스탬프, 이전/이후 값
데이터 접근 사용자, 엔드포인트, 범위, 타임스탬프, 레코드 수

인증 문제 해결

잘못된 API 키 오류

문제: "401 Unauthorized - Invalid API Key" 오류 발생

해결 방법:

  • 키 형식 확인 (sk_test_ 또는 sk_live_로 시작해야 함)
  • 키의 앞뒤 공백 확인
  • 키가 비활성화되거나 교체되지 않았는지 확인
  • 올바른 환경 사용 확인 (테스트 키는 테스트용, 라이브 키는 프로덕션용)
  • API 키 권한이 엔드포인트 요구 사항과 일치하는지 확인

토큰 만료 오류

문제: Bearer 토큰이 만료되어 요청 실패

해결 방법:

  • 리프레시 토큰을 사용하여 새로운 액세스 토큰 획득
  • 만료 5분 전에 자동 토큰 리프레시 구현
  • 리프레시 토큰을 안전하게 저장 (SPA의 경우 localStorage에 저장하지 않음)
  • 401 응답을 리프레시 토큰 흐름 시도로 처리

CORS/프리플라이트 오류

문제: 브라우저가 CORS 오류로 요청 차단

해결 방법:

  • 브라우저에서의 API 호출은 화이트리스트된 출처에서만 가능
  • 대시보드를 통해 도메인 추가: 설정 → CORS 출처
  • 브라우저가 자동으로 OPTIONS 프리플라이트 요청 전송
  • 개발 시 localhost:3000 또는 유사한 주소 사용

MFA 챌린지 완료 실패

문제: 올바른 코드 입력에도 MFA가 필요한 작업 실패

해결 방법:

  • 서버 시간 동기화 확인 (TOTP는 시간에 의존)
  • 코드는 30초 동안만 유효하므로 새로 생성
  • 인증 앱을 사용할 수 없는 경우 백업 코드 사용
  • 등록된 이메일을 통해 계정 복구 가능

오늘 바로 안전한 인증 구현

Smart Money API는 OAuth 2.0, JWT, MFA 및 SAML 통합을 지원하여 엔터프라이즈급 인증을 제공합니다. 업계 최고의 보안 관행으로 API 통합을 보호하세요.

엔터프라이즈 플랜 보기
SAML, IP 화이트리스트 또는 전용 지원이 필요하신가요? 영업팀에 문의하세요.

관련 리소스

인증 가이드 →

API 인증 시작하기

보안 모범 사례 →

포괄적인 보안 강화 가이드

오류 코드 참조 →

인증 오류 문제 해결
무료 시작 — 하루 100회 호출, 카드 불필요

한 API로 3개 거래소의 실시간 고래 흐름, 펀딩, 오픈 이자 및 온체인 데이터를 확인하세요. 무료 티어, 신용카드 불필요, 언제든지 업그레이드 가능.

무료 시작 →
실시간 API 콘솔 사용해보기 → (계정 불필요)