시작하기

인증

워크스페이스 API 키 발급·사용, 스코프, 레이트리밋, 응답 형식.

REST API 와 MCP 의 PAT 인증은 모두 워크스페이스 API 키를 Bearer 토큰으로 씁니다.

Bearer 토큰

모든 인증 요청에 Authorization 헤더를 붙입니다.

Authorization: Bearer pwk_xxxxxxxxxxxxxxxxxxxxxxxx

모든 워크스페이스 API 키는 pwk_ 로 시작합니다. 키는 평문이 아니라 SHA-256 해시로 저장됩니다. 발급 직후 한 번만 전체 값이 보이니 안전하게 보관하세요.

키 발급

Memory.Inc 앱 → 워크스페이스 → 설정 → API 에서 키를 만듭니다.

스코프

REST /v1/* 는 팀(워크스페이스) 스코프입니다 — 워크스페이스에 공유된 자료만 검색·관리하며, 멤버 개인(private) 자료는 포함되지 않습니다. 추가하는 메모리도 팀 공유로 들어갑니다.

개인 자료까지 포함한 검색이 필요하면 MCP 의 OAuth 토큰을 쓰세요 — 키 발급자의 개인 자료까지 포함합니다. MCP 인증 참고.

레이트리밋

읽기 /v1/* 엔드포인트는 IP·엔드포인트당 60초에 30요청으로 제한됩니다. 쓰기(POST /v1/memories)는 더 보수적으로 워크스페이스·IP당 60초에 10요청입니다. 초과 시 429 와 rate_limited 코드를 받습니다.

응답 형식

모든 /v1/* 응답은 일관된 envelope 를 씁니다.

// 성공
{ "ok": true, "data": { /* … */ } }
 
// 실패
{ "ok": false, "error": { "code": "validation", "message": "query is required" } }

에러 코드	HTTP
`validation`	400
`unauthorized`	401
`forbidden`	403
`not_found`	404
`conflict`	409
`rate_limited`	429
`internal`	500

자세한 내용은 에러·제한 을 보세요.

보안

키는 서버 측에서만 사용하세요. 클라이언트(브라우저·모바일)에 노출 금지.
키가 노출되면 앱에서 폐기하고 새로 발급하세요.
프로덕션·테스트용 키를 분리하면 회수가 쉽습니다.