# 에이전트 토큰 관리하기

> 토큰을 발급하고, 권한과 만료를 고르고, 교체하거나 폐기합니다. 토큰 값은 발급할 때 한 번만 보입니다.

에이전트 토큰은 에이전트가 MCP와 REST API에 쓰는 비밀입니다. `atk_agent_`로 시작합니다. 토큰 값은 발급이나 교체 직후 **한 번만** 보이고, 목록에는 `atk_agent_••••••••abcd`처럼 끝 네 글자만 보입니다.

> **주의 · 토큰이 샜다면**
>
> [바로 가기](https://docs.atmark.ai/connect/tokens#leak): 그 토큰을 먼저 교체하거나 폐기합니다.

## 시작하기 전에

- 토큰을 만들고 바꾸려면 역할이 소유자나 관리자여야 합니다.

![토큰 화면](https://docs.atmark.ai/_img/aaf761c445310d47/agent-tokens-ko-light.webp)

## 새 토큰 발급하기

쓰는 곳마다 이름을 붙인 토큰을 따로 두면, 샌 것 하나만 폐기하면 됩니다.

### 1. 새 토큰 열기

에이전트 화면의 **토큰**에서 **새 토큰**을 누릅니다.

### 2. 이름·권한·만료 고르기

**이름**은 쓰는 곳을 알아볼 이름입니다(60자까지). **권한**은 하나 이상 고릅니다. **만료**는 만료 없음, 30일, 90일, 365일 중에서 고릅니다.

### 3. 발급하고 챙기기

**발급하기**를 누르면 토큰 창이 열립니다. 토큰을 복사하거나 설정 메시지를 에이전트에게 보낸 뒤 확인란을 누르고 창을 닫습니다. 창을 닫으면 토큰을 다시 볼 수 없습니다.

![한 번만 보이는 토큰 창](https://docs.atmark.ai/_img/707cab599e699aeb/token-once-ko-light.webp)

한 에이전트가 가질 수 있는 활성 토큰 수는 요금제가 정합니다(최대 5개).

## 권한

| 권한 | 할 수 있는 일 |
|---|---|
| 보내기 `messages:send` | 새 메일, 회신, 전달, 예약 만들기와 취소, 웹훅 엔드포인트 삭제, 웹훅 재전송 |
| 읽기 `messages:read` | 받은 메일·스레드·첨부 읽기, 승인 상태, 인증 코드, 예약 목록과 조회, 웹훅 엔드포인트 등록과 목록, 웹훅 전달 기록 |
| 감사 `audit:read` | 발송 판정 기록 읽기 |
| 자기 정보 `agent:read_self` | 자기 정책 읽기(`get_my_policy`) |

읽기만 시키려면 **보내기**를 빼고 발급합니다. MCP 클라이언트에는 보내기 도구가 보이지 않습니다.

## 교체하기

토큰 값을 놓쳤거나 주기적으로 바꿀 때 씁니다.

1. 토큰 행의 **⋯** 메뉴에서 **교체**를 누릅니다.
2. 같은 이름·권한·기간으로 새 토큰이 발급되고, 지금 토큰은 바로 폐기됩니다.
3. 새 토큰을 에이전트 설정에 넣고 MCP를 다시 불러옵니다.

화면 위의 **전부 교체** 옆 화살표(▾)를 누르면 메뉴가 열립니다. **전부 교체**는 살아 있는 토큰을 모두 폐기하고 새 토큰 하나를 발급합니다. **전부 폐기**는 새 토큰 없이 모두 폐기합니다.

## 폐기하기

토큰 행의 **⋯** 메뉴에서 **폐기**를 누릅니다. 그 토큰을 쓰는 곳은 바로 끊기고, 다른 토큰은 그대로입니다.

> **되돌릴 수 없음 · 폐기는 되돌릴 수 없습니다**
>
> 폐기한 토큰은 다시 살릴 수 없습니다.

## 토큰이 샜다면

순서를 바꾸지 마세요. 먼저 끊고, 그다음 다시 연결합니다.

### 1. 샌 토큰 찾기

에이전트의 **토큰** 화면에서 **토큰 값** 열의 끝 네 글자로 샌 토큰을 찾습니다.

### 2. 교체하거나 폐기하기

그 행의 **⋯** 메뉴에서 **교체**를 누릅니다(다시 쓸 일이 없으면 **폐기**). 이 순간 옛 토큰은 무효가 됩니다. 교체하면 새 토큰 창이 뜨고, 새 토큰은 이 창에서 **한 번만** 보입니다. 바로 복사해 둡니다.

### 3. 새 토큰으로 다시 연결하기

쓰던 곳에 새 토큰을 넣고 다시 연결합니다. [Hermes](https://docs.atmark.ai/connect/mcp-hermes) · [Claude Code](https://docs.atmark.ai/connect/mcp-claude-code) · [Cursor](https://docs.atmark.ai/connect/mcp-cursor) · [그 밖의 클라이언트](https://docs.atmark.ai/connect/mcp-other-clients)

### 4. 쓰인 흔적 보기

토큰 목록의 **마지막 사용** 열과 **로그 › 발신** 탭에서, 모르는 발송이 없었는지 봅니다.

### 5. 붙여 넣은 곳 지우기

토큰을 대화, 문서, 이슈, 메신저 등에 붙여 넣었다면 그 메시지를 지웁니다.

긴급 정지는 토큰을 폐기하지 않습니다. 정지 중에도 샌 토큰으로 받은 메일을 읽을 수 있고, 정지를 풀면 그 토큰으로 다시 보낼 수 있습니다. 그래서 유출에는 폐기나 교체가 맞습니다.

## 토큰으로 할 수 없는 것

에이전트 토큰으로는 정책을 바꾸거나, 결제를 하거나, 에이전트를 만들거나, 조직 API 키를 읽을 수 없습니다. 토큰은 자기 에이전트의 메일과 정보에만 닿습니다.

---

원문: https://docs.atmark.ai/connect/tokens · 마지막 수정 2026-09-27