> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# API 토큰

> CLI, MCP, 직접 API 접근용 개인·워크스페이스 토큰.

Nora 로의 모든 프로그래매틱 접근 — CLI, MCP, 직접 API 호출 — 이 토큰 사용. 두 종류.

## 두 토큰 타입

| 타입            | 스코프                               | 최적 용도                |
| ------------- | --------------------------------- | -------------------- |
| **개인 API 토큰** | 여러분이 속한 모든 워크스페이스. 각각의 역할 따름.     | 인터랙티브 개발, 개인 CLI 사용. |
| **워크스페이스 토큰** | 하나의 워크스페이스. 커스텀 스코프. 사용자에 묶이지 않음. | CI/CD, 통합, MCP 서버.   |

둘 다 같은 방식으로 인증 (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 로

```bash theme={null}
export NORA_TOKEN="your-token"
nora flows list
```

또는 원샷:

```bash theme={null}
NORA_TOKEN="your-token" nora flows list
```

### MCP 로

MCP 서버 설정에 `NORA_TOKEN` 설정. [MCP 셋업](/ko/settings/connections/mcp) 참고.

### 직접 API 로

```bash theme={null}
curl -H "Authorization: Bearer $NORA_TOKEN" \
     https://api.platform.nora.my/v1/flows
```

## 로테이션

로테이션은 create-new + revoke-old:

1. Settings 에서 새 토큰 발급.
2. 소비 시스템 (CI env, MCP 설정 등) 의 토큰 업데이트.
3. 새 토큰 동작 검증.
4. 이전 토큰 취소.

"재생성" 작업 없음 — 교체가 명시적이라 무슨 일 일어나는지 앎.

CI 용:

```yaml theme={null}
env:
  NORA_TOKEN: ${{ secrets.NORA_TOKEN }}   # GH 에서 이 시크릿 로테이션 → Nora 에서 토큰 자체
```

## 취소

**Settings → Security → API tokens → 토큰 클릭 → Revoke**.

취소 즉시 — 토큰이 몇 초 안에 죽음. 사용 중인 기존 요청이 완료되거나 실패할 수 있음 (짧은 경쟁 윈도우); 새 요청이 401 로 실패.

즉시 취소:

* 누출 의심.
* 팀 멤버 떠남 (그들 개인 토큰 취소).
* 토큰 소유한 CI job 이나 서비스가 은퇴.

## 감사

모든 토큰 발급·사용·취소가 감사됨 ([감사 트레일](/ko/reliable/versions/audit) 참고):

* 누가 토큰 발급, 언제, 어느 스코프로.
* 각 API 호출을 어느 토큰이 인증 (편집됨; 값 아닌 토큰 ID 만).
* 모든 취소, 액터와 함께.

토큰 침해되면 감사 로그가 활성 중 토큰이 취한 정확한 액션 표시.

## 토큰 만료 정책

워크스페이스 정책 ([접근](/ko/settings/workspace/access) 참고) 이 강제 가능:

* **Max expiration** — 어떤 토큰도 N일 넘는 만료로 발급 불가.
* **필수 만료** — "never expires" 토큰 없음.
* **로테이션 리마인더** — N일 넘은 토큰이 UI 에 경고 표시.

규제 워크로드 권장: 90일 max 강제, 60일에 로테이션 리마인더.

## 개인 vs. 워크스페이스 결정 트리

* 내 노트북에만, 가끔? → 개인.
* CI, 봇, 팀 아무나 쓰는 MCP 서버? → 워크스페이스.
* 오늘만 실행하는 일회성 스크립트? → 개인 OK.
* 오래가는 것? → 워크스페이스.

## 관련

* [`nora auth`](/ko/cli/auth) — CLI 쪽 auth.
* [MCP 셋업](/ko/settings/connections/mcp) — 코딩 에이전트와 토큰 사용.
* [접근·정책](/ko/settings/workspace/access) — 역할 체크가 토큰에 적용.
* [감사 트레일](/ko/reliable/versions/audit) — 모든 토큰 이벤트 로깅.