> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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
```

## 로테이션

로테이션은 새로 만들고 옛것을 거두는 것입니다.

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일 상한을 강제하고 60일에 로테이션 리마인더를 두세요.

## 개인이냐 워크스페이스냐, 결정 트리

* 내 노트북에만, 가끔? → 개인.
* CI, 봇, 팀 누구나 쓰는 MCP 서버? → 워크스페이스.
* 오늘만 돌리는 일회성 스크립트? → 개인이면 됩니다.
* 오래가는 것? → 워크스페이스.

## 관련

* [`nora auth`](/ko/cli/auth) CLI 쪽 auth.
* [MCP 셋업](/ko/settings/connections/mcp) 코딩 에이전트와 토큰 쓰기.
* [접근·정책](/ko/settings/workspace/access) 역할 점검이 토큰에도 적용됩니다.
* [감사 트레일](/ko/reliable/versions/audit) 모든 토큰 이벤트가 기록됩니다.