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

# 외부 액세스 토큰

> CI 파이프라인, 웹훅 및 기타 자동화 서비스가 로그인 없이도 비공개 Replit 앱에 접근할 수 있도록 합니다.

외부 액세스 토큰은 특정 Replit App을 위해 발급하는 bearer token입니다.
CI 파이프라인, 웹훅, 상태 확인 핑어, Slack 봇, 내부 스크립트 등의 자동화 서비스가
[Private Dev URL](/references/publishing/private-deployments) 또는
[Private Deployment](/references/publishing/private-deployments)으로 잠긴 앱에
접근할 수 있도록 해줍니다.

각 토큰을 비밀번호처럼 취급하세요. 토큰을 가진 사람은 누구든 토큰이 만료되거나
revoke되기 전까지 앱에 접근할 수 있습니다.

<Note>
  외부 액세스 토큰은 Replit Core 및 Pro 플랜에서 사용할 수 있습니다.
  Enterprise 고객은 기능이 워크스페이스에 활성화되기 전에 Replit에 opt-in을 요청해야 합니다.
  토큰은 배포가 비공개로 설정된 이후에만 퍼블리싱 설정에 표시됩니다.
</Note>

## 토큰을 사용해야 하는 경우

브라우저 외부에서 비공개 Replit App을 호출해야 할 때 외부 액세스 토큰을 사용하세요.
일반적인 사용 사례는 다음과 같습니다:

* 매 커밋마다 dev URL에 대해 스모크 테스트를 실행하는 GitHub Actions 워크플로우.
* 퍼블리시된 앱의 헬스 엔드포인트를 확인하는 업타임 모니터 (Better Stack, Pingdom, UptimeRobot).
* Private Deployment로 POST 요청을 보내는 웹훅 수신자 — Stripe, Slack, GitHub.
* 디버깅 중 팀원의 머신에서 실행하는 `curl` 또는 `fetch` 호출.

외부 액세스 토큰은 브라우저에서 UI 페이지를 여는 용도가 아닌 **API 트래픽**을 위해 설계되었습니다.
단일 페이지 앱(Vite, Next.js 등)은 후속 요청으로 JavaScript 번들을 로드하는데,
이 요청에는 토큰이 포함되지 않아 실패합니다. 대화형 브라우징을 위해서는 정상적으로 로그인하세요.

## 토큰 환경

각 토큰은 하나의 환경에 바인딩됩니다:

| 환경            | 적용 범위                                  | 용도                              |
| :------------ | :------------------------------------- | :------------------------------ |
| `Development` | 앱의 워크스페이스 dev URL (`*.replit.dev`)     | 개발 중 실행 중인 Repl에 접근             |
| `Production`  | 앱의 퍼블리시된 배포 (`*.replit.app` 및 커스텀 도메인) | 외부 서비스에서 Private Deployment에 접근 |

`Production` 토큰은 *현재 퍼블리시된* 배포에 연결됩니다. 새 배포로 다시 퍼블리시하면
기존 production 토큰이 더 이상 작동하지 않으므로 새 토큰을 발급해야 합니다.

## 외부 액세스 토큰 생성

<Steps>
  <Step>
    노출하려는 앱을 열고 **Publishing** 툴을 엽니다.
  </Step>

  <Step>
    **Adjust settings**를 선택하여 재배포 옵션을 펼칩니다.
  </Step>

  <Step>
    **Security** 섹션에서 **External access tokens**를 찾습니다.
  </Step>

  <Step>
    **Create access token**을 선택하고 다음을 입력합니다:

    * **Label** (선택사항): 나중에 토큰을 식별할 수 있는 짧은 이름.
      예: `CI` 또는 `Stripe webhook`. 최대 120자.
    * **Environment**: 호출하는 서비스가 앱에 접근해야 하는 위치에 따라
      `Development` 또는 `Production`을 선택합니다.
    * **Expires after**: 유효 기간을 선택합니다 — `1 hour`, `24 hours`, `7 days`,
      `30 days`, `3 months`, `1 year`, `5 years`. 작업에 맞는 가장 짧은 기간을 선택하세요.
      "만료 없음" 옵션은 없습니다.
  </Step>

  <Step>
    **Create**를 선택합니다.
  </Step>
</Steps>

Replit은 토큰을 **한 번만** 보여줍니다. 지금 복사하세요 — 다이얼로그를 닫으면
토큰을 다시 볼 방법이 없습니다. 분실한 경우 해당 토큰을 revoke하고 새 토큰을 발급하세요.

공개 화면에는 두 가지 복사 액션이 있습니다:

* **Copy query parameter** — URL에 추가할 `?project-protection-bypass=<token>`을 복사합니다.
  빠른 `curl` 확인에 편리합니다.
* **Copy token only** — `Authorization: Bearer` 헤더로 전송하기에 적합한
  원시 토큰을 복사합니다.

<Info>
  첫 번째 토큰을 생성하면 아직 활성화되지 않은 경우 앱의 외부 액세스가 자동으로 켜집니다.
  보호 없이는 토큰이 우회할 것이 없습니다.
</Info>

## 토큰 사용 방법

다음 두 가지 방법 중 하나로 토큰을 제시하세요:

### Authorization 헤더 (권장)

```bash theme={null}
curl -H "Authorization: Bearer <token>" https://your-app.replit.app/health
```

웹훅, CI 스크립트, 백엔드 간 호출 등 거의 모든 경우에 올바른 선택입니다.
토큰이 URL을 캡처하는 로그에 나타나지 않으며 브라우저 기록에도 남지 않습니다.

### 쿼리 파라미터

```bash theme={null}
curl "https://your-app.replit.app/health?project-protection-bypass=<token>"
```

헤더를 설정할 수 없는 경우에만 쿼리 파라미터 방식을 사용하세요 — 예를 들어
URL만 입력받는 서비스. 토큰이 포함된 URL은 프록시 로그, 셸 기록, 스크린샷에
남을 수 있으므로 가능한 경우 헤더 방식을 선호하세요.

## 기존 토큰 관리

**External access tokens** 섹션에는 앱에 대해 생성한 모든 토큰이 최신순으로
나열되며, 레이블, 환경, 생성일, 만료일, revocation 상태가 표시됩니다.
전체 값은 생성 시에만 표시되므로 각 행에는 토큰의 마지막 몇 글자가 표시되어
토큰을 구별하는 데 도움이 됩니다.

표시되는 토큰은 *본인*이 생성한 것만 해당됩니다. 앱을 소유하고 있더라도
다른 협업자의 토큰은 그들에게만 비공개로 표시됩니다.

## 토큰 revoke

토큰이 더 이상 필요하지 않을 때, 또는 유출 가능성이 있을 때 즉시 revoke하세요.
revoke 방법:

<Steps>
  <Step>
    앱의 퍼블리싱 설정에서 **External access tokens** 섹션을 엽니다.
  </Step>

  <Step>
    목록에서 토큰을 찾아 휴지통 아이콘을 선택합니다.
  </Step>

  <Step>
    revocation을 확인합니다.
  </Step>
</Steps>

Revocation은 **즉각적이며 되돌릴 수 없습니다**. 해당 토큰을 사용하는 트래픽은
몇 초 내에 거부되기 시작합니다. 다시 접근이 필요하다면 새 토큰을 발급하세요.

본인이 직접 생성한 토큰만 revoke할 수 있습니다. 워크스페이스에서 협업자를 제거하면
해당 앱에 대해 그들이 발급한 토큰이 자동으로 revoke됩니다.

## 토큰을 안전하게 관리하기

외부 액세스 토큰은 자격 증명입니다. API 키나 비밀번호와 동일한 수준으로 취급하세요.

### 해야 할 것

* **시크릿 매니저에 토큰을 저장하세요** — GitHub Actions secrets, CI 벤더의 vault,
  클라우드 제공자의 시크릿 스토어, 또는 패스워드 매니저.
  절대 저장소에 커밋하지 마세요.
* **가능하면 짧은 유효 기간을 사용하세요.** 일회성 통합을 위한 7일 토큰이
  방치된 5년 토큰보다 안전합니다.
* **모든 토큰에 레이블을 붙이세요.** 나중에 어떤 용도인지, 아직 사용 중인지
  알 수 있도록 하세요. 레이블 없는 토큰이 가장 먼저 유출되고 가장 나중에 revoke됩니다.
* **소비자별로 별도의 토큰을 발급하세요.** CI 작업 하나당 토큰 하나, 웹훅 소스 하나당
  토큰 하나, 업타임 체크 하나당 토큰 하나. 무언가가 침해되거나 벤더가 더 이상
  필요하지 않을 때 해당 토큰만 revoke하면 됩니다.
* **쿼리 파라미터보다 `Authorization` 헤더를 선호하세요.** URL 로그, 브라우저 기록,
  referer 헤더를 통해 토큰이 유출되지 않도록 합니다.
* **노출 가능성이 있다면 즉시 revoke하세요** — 유출된 로그, 공개 저장소 커밋,
  화면 공유, 전 직원의 노트북. Revocation은 즉시 적용됩니다; 이후 대체 토큰을 발급하세요.

### 하지 말아야 할 것

* **팀원이나 서비스 간에 토큰을 공유하지 마세요.** 두 시스템이 하나의 토큰을 공유하면
  하나를 revoke할 때 다른 것도 중단됩니다.
* **채팅, 이메일, 스크린샷, 이슈 트래커에 토큰을 붙여넣지 마세요.**
  이러한 채널은 예측하기 어려운 방식으로 보관, 인덱싱, 공유됩니다.
* **클라이언트 측 코드에 토큰을 삽입하지 마세요** — 브라우저 앱, 모바일 앱,
  데스크톱 바이너리. 사용자 기기로 배포된 모든 것은 공개된 것으로 간주해야 합니다.
* **브라우저 세션에 토큰을 사용하지 마세요.** 토큰은 API 호출에 사용되며
  브라우저 탭에서 SPA를 로드하는 데는 적합하지 않습니다. 그런 경우에는
  정상적인 Replit 로그인을 사용하세요.
* **기본값으로 5년 만료를 선택하지 마세요.** 소비자가 실제로 접근이 필요한 기간에
  맞추어 유효 기간을 설정하세요.

## 문제 해결

<Accordion title="프로덕션 토큰이 갑자기 작동하지 않습니다">
  Production 토큰은 특정 퍼블리시된 배포에 바인딩됩니다. 배포 유형을 변경하거나
  배포를 삭제하고 다시 만드는 등의 방법으로 앱을 다시 퍼블리시한 경우
  기존 production 토큰이 무효화됩니다. 새 배포의 설정에서 새 토큰을 발급하세요.
</Accordion>

<Accordion title="토큰이 `curl`에서는 작동하지만 브라우저에서는 여전히 로그인 페이지가 표시됩니다">
  외부 액세스 토큰은 브라우저 세션이 아닌 API 트래픽을 위한 것입니다.
  단일 페이지 앱이 브라우저에서 로드될 때 초기 HTML 요청은 쿼리 파라미터를 통해
  토큰을 전달할 수 있지만, JavaScript 번들, CSS, API 호출에 대한 후속 요청에는
  토큰이 포함되지 않아 거부됩니다. 앱을 대화형으로 탐색하려면 Replit에 정상적으로
  로그인하세요.
</Accordion>

<Accordion title="토큰을 분실했습니다 — 다시 볼 수 있나요?">
  아니요. Replit은 생성 시 한 번만 토큰을 표시합니다. 목록 뷰에는 메타데이터
  (레이블, 환경, 만료일, 마지막 몇 글자)만 표시되며 전체 토큰 값은 표시되지 않습니다.
  분실한 경우 해당 토큰을 revoke하고 새 토큰을 생성하세요.
</Accordion>

## 다음 단계

* [Private Deployments](/references/publishing/private-deployments):
  이 토큰이 우회하는 기반 액세스 제어 기능.
* [Replit App Access Management](/teams/identity-and-access-management/repl-access-management):
  비공개 앱에 로그인할 수 있는 Replit 사용자를 관리합니다.