Mind Key vs JWT — 언제 무엇을?

Synapse에는 두 가지 인증 토큰이 있습니다. 잘못 선택하면 401 오류가 발생합니다. 이 가이드는 명확한 결정 프레임워크를 제공합니다.

빠른 결정 표

단순한 규칙

Mind Key — 데이터 접근 토큰

Mind Key는 하나의 마인드 데이터에 접근 권한을 부여합니다. 만료되지 않는 (마인드가 삭제될 때까지) 장기 토큰입니다. 다음에 적합:

• 세션 간 메모리를 유지하는 LLM 에이전트
• 백그라운드 cron 작업
• MCP 서버 구성
• 웹훅 통합
• 메모리를 읽는 모바일 앱

Mind Key가 할 수 있는 것

• GET /memory/recall — 이 마인드의 모든 메모리 읽기
• POST /memory — 메모리 저장/업데이트
• GET /chat/poll — 채팅 메시지 읽기
• POST /chat/reply — 채팅 메시지 전송
• GET /mind/tasks — 작업 나열
• POST /mind/task — 작업 생성
• POST /script — 스크립트 저장
• POST /webhooks — 웹훅 등록
• POST /computers/:id/commands — 컴퓨터 명령 큐잉

Mind Key가 할 수 없는 것

• 마인드 생성 / 나열 / 삭제 (JWT 필요)
• 다른 사용자와 마인드 공유 (JWT 필요)
• 사용자 계정 정보 보기 (JWT 필요)
• 웹 푸시 구독 (JWT 필요)

JWT — 계정 관리 토큰

JWT는 사용자 계정을 인증합니다. 7일 후에 만료되며 여러 마인드에 걸치거나 다른 사용자와 관련된 계정 수준 작업에 사용됩니다.

JWT가 할 수 있는 것

• POST /minds — 새 마인드 생성 (새 Mind Key 반환)
• GET /minds — 이 사용자의 모든 마인드 나열
• DELETE /minds/:id — 마인드 삭제
• POST /sharing — 다른 사용자와 마인드 공유
• POST /push/subscribe — 웹 푸시 알림 구독
• GET /sharing — 마인드 공유 나열

JWT가 할 수 없는 것

• 메모리 읽기 / 쓰기 (Mind Key 필요)
• 채팅 메시지 전송 (Mind Key 필요)
• 작업 관리 (Mind Key 필요)
• 웹훅 등록 (Mind Key 필요)

특수 사례: Computer Token

/computers/me/* 엔드포인트 (에이전트 측, screen-remote-agent용)는 세 번째 토큰 유형인 Computer Token을 사용합니다. 이 토큰은 설치 코드를 상환할 때 POST /computers/register에 의해 반환되며, 하나의 등록된 컴퓨터에 특정합니다.

일반적인 패턴

패턴 1: 단일 LLM 에이전트

1. 한 번 가입 → JWT 획득
2. 하나의 마인드 생성 → Mind Key 획득
3. LLM이 모든 것에 Mind Key 사용

패턴 2: 다중 프로젝트 에이전트

1. 한 번 가입 → JWT 획득
2. 여러 마인드 생성 (work, personal, project-x) → 여러 Mind Key 획득
3. LLM이 컨텍스트에 따라 다른 Mind Key 로드

패턴 3: 팀 공유

1. 사용자 A가 마인드 생성 → Mind Key A 획득
2. 사용자 A가 JWT로 사용자 B와 공유 (POST /sharing)
3. 사용자 B는 이제 자신의 JWT로 접근 가능
4. LLM 접근을 위해 사용자 B는 자체 Mind Key 생성 필요 (또는 A의 것 사용)

패턴 4: MCP 서버

MCP 서버는 항상 Mind Key 사용 (SYNAPSE_MIND_KEY 환경 변수로 설정). 하나의 MCP 서버 인스턴스 = 하나의 마인드. 다중 마인드 접근을 위해 여러 MCP 인스턴스를 실행하거나 클라이언트 측 마인드 전환을 구현하십시오.

토큰 형식 치트 시트

다음 단계

• Authentication — 전체 인증 가이드
• User 및 Minds API — JWT로 보호된 엔드포인트
• Memory API — Mind Key로 보호된 엔드포인트