보안과 데이터

API 키 관리

• API 키(alt_live_...)의 전체 값은 생성할 때 한 번만 표시됩니다. Alt는 시크릿 원문을 저장하지 않으므로 나중에 다시 확인할 수 없습니다. 키를 잃어버리면 새로 발급하세요.
• 웹훅 서명 시크릿(whsec_...)의 전체 값도 생성할 때 한 번만 표시됩니다. Alt는 시크릿을 AES-256-GCM으로 암호화해 저장하고 웹훅에 서명할 때만 사용하므로 콘솔에서 다시 확인할 수 없습니다. 교체하려면 엔드포인트를 다시 만들어 새 시크릿을 발급하세요.
• 키는 시크릿 매니저에 보관하세요. 클라이언트 코드, 모바일 앱, 저장소에는 절대 넣지 마세요.
• 키를 교체하려면 콘솔에서 같은 연동에 새 키를 발급하세요. 시스템이 새 키를 사용하도록 바꾼 뒤 기존 키를 폐기하면 됩니다. 키 폐기는 즉시 적용됩니다.
• 키를 만들 때 만료일을 지정할 수도 있습니다. 만료된 키는 자동으로 거부됩니다.
• 시스템마다 별도의 키를 사용하세요. 스테이징과 프로덕션 키를 분리하면 한쪽 키를 폐기해도 다른 환경은 계속 동작합니다.
• 샌드박스나 테스트 모드는 없습니다. 발급되는 모든 API 키는 실제 노트에 접근합니다. 스테이징과 프로덕션은 별도의 연동으로 분리하세요. 실제 녹음을 기다리지 않고 수신 서버를 확인하려면 엔드포인트를 만들 때 전송되는 endpoint.verification 이벤트나 콘솔의 테스트 전송을 사용하세요.

접근할 수 있는 데이터

• 개인 연동은 연동 소유자의 개인 노트만 조회할 수 있습니다. 팀스페이스 연동은 해당 팀스페이스에 공유된 노트만 조회할 수 있으며, 멤버의 개인 노트에는 접근할 수 없습니다.
• 팀스페이스 연동은 해당 팀스페이스의 소유자만 만들 수 있습니다.
• API 키의 조회 범위를 벗어난 노트를 요청하면 404를 반환합니다. 응답만으로는 해당 노트가 존재하는지도 알 수 없습니다.
• 노트가 범위를 벗어나면 note.deleted (reason: access_lost)를 받고 목록에서도 사라집니다. 저장해 둔 사본을 지우거나 접근을 차단하세요.

권한 범위(scope)

연동에 꼭 필요한 권한 범위만 부여하세요. API 키에 부여되지 않은 권한이 필요한 요청은 403 insufficient_scope로 실패합니다.

API 요청 한도

• API 키 하나당 분당 최대 120회 요청할 수 있습니다. 한도를 초과하면 Retry-After 헤더와 함께 429 rate_limited를 반환합니다. 헤더가 안내하는 시간만큼 기다린 뒤 다시 요청하세요.
• 짧은 간격으로 전체 목록을 반복해서 조회하기보다 웹훅과 updated_after를 사용하세요. 마지막 동기화 이후 변경된 노트만 가져올 수 있습니다.
• 노트, 전사, 요약 응답의 ETag를 저장하고 다음 요청의 If-None-Match 헤더에 전달하세요. 내용이 바뀌지 않았다면 본문 없이 304를 반환하므로 불필요한 데이터 전송을 줄일 수 있습니다.

개인정보

• 전사와 요약은 사용자 콘텐츠이며 개인정보가 포함될 수 있습니다. 연동에 필요한 데이터만 가져오고, 저장한 데이터는 안전하게 보호해야 합니다.
• 노트 삭제도 반드시 반영해야 합니다. note.deleted를 받으면 이유와 관계없이 저장한 사본을 지우거나 접근을 차단하세요. 이벤트를 놓칠 수 있으므로 주기적으로 전체 목록을 확인해 누락된 변경 사항도 반영해야 합니다.
• 웹훅 URL은 공개 HTTPS 엔드포인트여야 합니다. Alt는 사설 주소, 루프백 주소, 클라우드 메타데이터 주소를 거부하며 리다이렉트를 따라가지 않습니다.
• API를 사용하려면 연동이 속한 워크스페이스에 활성 구독이 있어야 합니다. 구독이 없으면 요청은 403 plan_required로 실패합니다.
• Alt가 사용자 데이터를 어떻게 다루는지는 개인정보처리방침을 참고하세요.