토큰 두 종류
둘 다 같은 방식으로 인증합니다(Bearer 헤더). 차이는 스코프와 한살이입니다.
개인 API 토큰
Settings → Security → API tokens → Personal → New token 입니다. 이렇게 정합니다.- Name 사람이 읽을 라벨. “MacBook CLI”, “Home Cursor”.
- Expiration 선택. Never / 30일 / 90일 / 1년.
워크스페이스 토큰
Settings → Security → API tokens → Workspace → New token 입니다. 이렇게 정합니다.- Name “GitHub Actions CI”, “internal Slack bot”, “온콜 팀용 Cursor”.
- Scope 토큰이 무엇을 할 수 있는지.
- Read-only Flow·트레이스를 보되 쓰기는 못 합니다.
- Read-write, no publish 다 고치되 프로덕션 출시는 못 합니다.
- Full 워크스페이스 최고 역할 멤버가 할 수 있는 전부.
- Custom 작업을 골라 담습니다.
- Expiration 개인과 같은 옵션.
- 개인에 안 묶입니다. 팀원이 떠나도 토큰이 계속 됩니다.
- 스코프가 좁습니다. 읽기 전용 토큰이 실수로 배포 못 합니다.
- 감사가 깔끔합니다. 감사 로그가 개인 이름이 아니라 “워크스페이스 토큰: GitHub Actions CI” 를 보여줍니다.
토큰 쓰기
CLI로
MCP로
MCP 서버 설정에NORA_TOKEN을 둡니다. MCP 셋업을 참고하세요.
직접 API로
로테이션
로테이션은 새로 만들고 옛것을 거두는 것입니다.- Settings에서 새 토큰을 발급합니다.
- 쓰는 시스템(CI env, MCP 설정 등)의 토큰을 업데이트합니다.
- 새 토큰이 되는지 확인합니다.
- 이전 토큰을 거둡니다.
거두기
Settings → Security → API tokens → 토큰을 눌러 → Revoke 입니다. 거두기는 즉시입니다. 토큰이 몇 초 안에 죽습니다. 진행 중이던 요청은 끝나거나 실패할 수 있고(짧은 경쟁 구간), 새 요청은 401로 실패합니다. 이럴 때 바로 거두세요.- 새는 게 의심될 때.
- 팀원이 떠날 때(그 개인 토큰을 거둡니다).
- 토큰을 가진 CI job이나 서비스가 은퇴할 때.
감사
모든 토큰 발급·사용·거두기가 감사됩니다(감사 트레일 참고).- 누가 토큰을 발급했고, 언제, 어느 스코프로.
- API 호출마다 어느 토큰이 인증했는지(가려진 채, 값이 아니라 토큰 ID만).
- 모든 거두기, 행위자와 함께.
토큰 만료 정책
워크스페이스 정책(접근 참고)이 강제할 수 있습니다.- Max expiration 어떤 토큰도 N일 넘는 만료로 못 발급합니다.
- 필수 만료 “never expires” 토큰이 없습니다.
- 로테이션 리마인더 N일 넘은 토큰이 UI에 경고를 띄웁니다.
개인이냐 워크스페이스냐, 결정 트리
- 내 노트북에만, 가끔? → 개인.
- CI, 봇, 팀 누구나 쓰는 MCP 서버? → 워크스페이스.
- 오늘만 돌리는 일회성 스크립트? → 개인이면 됩니다.
- 오래가는 것? → 워크스페이스.