---
title: 인증과 권한
description: 웹 세션, Android SDK 액세스 토큰, 앱 범위 에이전트 토큰의 사용 범위.
---

# 인증과 권한

외부 도구와 MCP에는 **앱 범위 에이전트 토큰**을 사용합니다. 웹 로그인 세션과 Android SDK 액세스 토큰은 각각 다른 용도이며 서로 대체할 수 없습니다.

## 인증 방식 선택

| 인증 방식            | 사용자                  | 사용 범위                                                     |
| -------------------- | ----------------------- | ------------------------------------------------------------- |
| 웹 세션              | 로그인한 앱 소유자      | 개발자 콘솔, 에이전트 토큰 발급·조회·철회, 해당 앱 자동화 API |
| 에이전트 Bearer 토큰 | 개발 도구·MCP·서버 통합 | 토큰이 발급된 앱의 자동화 API. 토큰 관리 제외                 |
| SDK Bearer 토큰      | 앱 테스트 참여자        | SDK 접근 확인과 피드백 제출. 개발자 자동화 API에는 사용 불가  |

SDK 토큰은 테스트 참여 승인과 브라우저 인증을 거쳐 발급됩니다. [SDK 인증 흐름](/sdk/authentication)을 참고하세요.

## 에이전트 토큰 발급

1. 앱 소유자로 OpenTester에 로그인합니다.
2. 개발자 콘솔에서 앱의 **앱 정보 및 SDK → 코딩 에이전트 연결**을 엽니다.
3. 용도를 구분할 이름과 권한, 만료 기간을 정하고 발급합니다.
4. 한 번 표시되는 원문을 비밀 관리 도구나 로컬 실행 환경에 보관합니다.

토큰은 `ot_agent_`로 시작합니다. 발급한 뒤에는 원문을 다시 조회할 수 없습니다. 분실하거나 만료되면 새 토큰을 발급하세요. [토큰 관리 API](/api/tokens)에서도 같은 정책을 사용합니다.

### 권한

| Scope              | 허용 동작                |
| ------------------ | ------------------------ |
| `feedback:read`    | 피드백 목록·상세 조회    |
| `work-items:read`  | 수정 작업 목록·상세 조회 |
| `work-items:write` | 수정 작업 생성·PR 연결   |

권한은 독립적입니다. `work-items:write`가 있어도 피드백 조회에는 `feedback:read`가 필요합니다. 읽기 전용 도구는 조회 권한만 발급하면 됩니다.

### 요청 헤더

```http
Authorization: Bearer ot_agent_YOUR_TOKEN
```

위 문자열은 형식 설명용입니다. 실제 발급된 토큰 전체를 보내세요.

```sh
curl --fail-with-body \
  "$OPENTESTER_API_URL/apps/$OPENTESTER_APP_ID/automation/change-requests" \
  --header "Authorization: Bearer $OPENTESTER_AGENT_TOKEN"
```

토큰은 발급된 앱에서만 작동합니다. 서버는 요청마다 만료·철회·현재 앱 소유자·권한을 확인합니다. 다른 앱에는 같은 소유자의 토큰이라도 사용할 수 없습니다.

## 웹 세션과 Origin

웹 로그인은 HttpOnly `opentester_session` 쿠키를 사용합니다. 토큰 관리 API는 웹 세션만 허용하며, `Authorization` 헤더가 있으면 거부합니다.

웹 세션으로 `POST`, `PATCH`, `PUT`, `DELETE`를 요청할 때는 서비스에서 허용한 `Origin`이 필요합니다. 개발자 콘솔과 같은 Origin의 브라우저 요청은 이를 자동으로 보냅니다. 별도 `docs.` 도메인에서 브라우저 쿠키를 이용해 콘솔 API를 호출하는 방식은 지원하지 않습니다.

자동화 API의 피드백·수정 작업 경로는 유효한 형식의 에이전트 Bearer 요청에 한해 웹 Origin 검사 대상에서 제외됩니다. 따라서 MCP나 서버 프로그램은 웹 세션 없이 호출할 수 있습니다.

::: warning 인증 혼합
`Authorization` 헤더가 있으면 에이전트 토큰만 검사합니다. 잘못된 토큰을 보내도 함께 보낸 브라우저 쿠키로 대신 인증하지 않습니다. 토큰 관리 요청에서는 `Authorization` 헤더를 아예 제외하세요.
:::

## 보관과 교체

토큰 원문을 Git 저장소, 공개 로그, 이슈, 에이전트 프롬프트에 넣지 마세요. 환경변수 이름만 설정 파일에 공유하고 값은 실행 환경에서 전달합니다. Android 앱에 개발자 토큰을 포함하지 마세요.

사용을 중단한 도구의 토큰은 개발자 콘솔에서 철회합니다. 철회하면 이후 요청은 인증에 실패합니다. 새 토큰으로 교체한 뒤 MCP 프로세스도 다시 연결하세요.