# 인증 및 Mind Key
SUMMARY: Synapse 인증 작동 방식: 에이전트용 Mind Key, 사람용 JWT, URL 전용 도구용 ?key=.

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

인증 및 Mind Key
Synapse는 두 가지 인증 방법을 사용하며, 각각 다른 사용 사례에 최적화되어
있습니다. 신뢰할 수 있는 통합을 구축하려면 차이를 이해하는 것이 필수적입니다.
두 가지 인증 방법
| 방법 | 사용 사례 | 속도 제한 | 만료 |
|--------|----------|------------|--------|
| Mind Key | LLM 에이전트, 자동화 도구 | 없음 (헤더) / 분당 60회 (쿼리) | 없음 |
| JWT | 사용자 대면 UI, 계정 작업 | 없음 | 7일 |
Mind Key (에이전트용)
Mind Key는 테넌트 범위의 API 토큰입니다. 단일 마인드의 데이터 (메모리, 작업,
채팅, 스크립트 등)를 인증합니다. 다음에 사용하십시오:
- API를 호출하는 LLM 에이전트
- 백그라운드 자동화 스크립트
- MCP 서버 구성
- 모든 장기 통합
헤더 인증 (권장)
[CODE BLOCK]
쿼리 파라미터 (URL 전용 도구용)
[CODE BLOCK]
> [!WARNING]
>  쿼리 파라미터는 분당 60회로 제한됩니다.
> Bearer 헤더는 속도 제한이 없습니다. 클라이언트가 커스텀 헤더를 지원할
> 때마다 헤더를 사용하십시오.
Mind Key 생성
[CODE BLOCK]
응답에 가 포함됩니다 — 즉시 저장하십시오, 한 번만 표시됩니다.
마인드 나열
[CODE BLOCK]
마인드 삭제 (되돌릴 수 없음!)
[CODE BLOCK]
JWT (사람용)
JWT는 특정 마인드가 아닌 사용자 계정을 인증합니다. 다음에 사용하십시오:
- 계정 가입 및 로그인
- 마인드 생성 / 나열 / 삭제
- 다른 사용자와 마인드 공유
- Web Push 구독 관리
가입
[CODE BLOCK]
반환: 
로그인
[CODE BLOCK]
반환: 
JWT 만료
JWT는 7일 후에 만료됩니다. JWT가 만료되면 을 다시 호출하여
새 것을 받으십시오. Mind Key는 만료되지 않으므로 기존 에이전트 통합은
계속 작동합니다.
보안 모범 사례
> [!CRITICAL]
> - Mind Key를 git에 절대 커밋하지 마십시오. 환경 변수를 사용하십시오.
> - Mind Key를 로그에 남기지 마십시오. 로그에서 마스킹 ().
> - 유출이 의심되면 키 교체 (마인드 삭제, 새로 생성).
> - 키가 유출된 경우 피해 범위를 제한하기 위해 프로젝트당 하나의 마인드 사용.
환경 변수 패턴
[CODE BLOCK]
[CODE BLOCK]
MCP 서버 구성
[CODE BLOCK]
다중 마인드 패턴
각 사용자는 여러 마인드를 가질 수 있습니다. 일반적인 패턴:
| 마인드 이름 | 용도 |
|-----------|---------|
|  | 업무 관련 메모리 |
|  | 개인 선호도, 가족 |
|  | 특정 프로젝트 컨텍스트 |
|  | 학습 진행 상황 |
|  | 범용 폴백 |
컨텍스트를 격리하기 위해 다른 LLM 세션에서 다른 Mind Key를 사용하십시오.
속도 제한
| 인증 방법 | 제한 | 범위 |
|-------------|-------|-------|
| Mind Key (헤더) | 없음 | 마인드별 |
| Mind Key (?key=) | 분당 60회 | IP별 |
| JWT (헤더) | 없음 | 사용자별 |
| 공용 엔드포인트 | 없음 | 전역 |
속도 제한 헤더 (, , )는
해당되는 경우 응답에 포함됩니다.
다음 단계
- Mind Key vs JWT — 언제 무엇을 사용할지
- Memory API — Mind Key로 할 수 있는 것
- User API — JWT로 계정 관리