API 토큰 관리, 다시 생성 및 취소
API 토큰을 찾고, 시크릿을 다시 생성하며(24시간 중첩 옵션 제공), 토큰을 취소하고, 만료 및 IP 허용 목록을 이해하며, 토큰이 작동하지 않는 이유를 확인하세요.
토큰 탭에는 액세스 권한, 제한 사항 및 마지막 사용 기록이 포함된 API 토큰이 나열됩니다. 여기에서 토큰의 시크릿을 다시 생성하거나, 토큰을 취소하고, 토큰이 작동하지 않는 이유를 확인할 수 있습니다.
토큰을 찾는 방법
워크스페이스 메뉴를 열고 AI agents & API를 선택하세요. 토큰 탭이 첫 번째 탭이며, 각 탭에는 개수가 표시됩니다.
토큰 확인 권한:
| 역할 | 확인 가능 범위 | 수행 가능 작업 |
|---|---|---|
| 소유자 또는 관리자 | "이 워크스페이스의 모든 토큰. 멤버는 자신의 토큰만 볼 수 있습니다." 소유자 메뉴로 사람별 필터링 가능(모두 선택 시 전체 표시). | 모든 토큰 취소 가능. 본인 토큰만 다시 생성 가능. |
| 편집자 또는 콘텐츠 제작자 | "본인의 토큰. 해당 토큰을 사용하는 에이전트는 본인으로 간주되어 작동합니다." | 본인 토큰 취소 및 다시 생성 가능. |
각 행에는 이름(시크릿의 마지막 문자 포함, 예: clv_agent_…k7Qe), 소유자, 액세스(권한), 포함된 사이트, 생성됨, 마지막 사용 및 만료일이 표시됩니다. 바닥글에는 워크스페이스의 제한 대비 활성 토큰 수가 표시됩니다. 행에 표시되는 배지:
| 배지 | 의미 |
|---|---|
| 크레딧 사용 | 토큰에 credits:spend이 설정됨. 마우스를 올리면 제한 사항 확인 가능: 작업당, 일일, 월간 ("제한 없음"은 비어 있음) 및 "n 크레딧 미만 자동 승인" 또는 "유료 시작 시마다 승인 필요". |
| IP 제한됨 | 토큰에 IP 허용 목록이 설정되어 해당 주소에서만 작동함. |
| 역할 범위를 초과함 | "소유자의 역할이 변경되었습니다. 취소선이 그어진 권한이 필요한 호출은 거부됩니다." |
| 취소됨 / 만료됨 | 토큰이 더 이상 작동하지 않음. 옆에 이유가 표시됨(토큰이 작동하지 않는 이유 참조). |
취소 및 만료된 토큰은 기본적으로 숨겨집니다. **취소 및 만료된 토큰 표시 (count)**를 클릭하여 나열하세요. 해당 토큰은 30일 동안 목록에 유지됩니다.
토큰의 액세스 권한 변경
토큰의 권한, 사이트, 만료일, 크레딧 사용 제한 및 IP 허용 목록은 생성 후 편집할 수 없습니다. 변경하려면 새 토큰을 생성하여 설정을 적용하고, 에이전트를 전환한 뒤 이전 토큰을 취소하세요.
토큰의 시크릿 다시 생성
시크릿이 유출되었을 가능성이 있거나 정기적으로 교체해야 할 때 다시 생성하세요. 새 시크릿은 동일한 이름, 액세스, 사이트, IP 허용 목록, 크레딧 사용 제한 및 만료일을 가집니다.
토큰 메뉴 열기
토큰 탭에서 해당 토큰 행의 ⋯ 메뉴를 열고 시크릿 다시 생성을 선택하세요.
이전 시크릿 중단 시점 선택
대화 상자에 "name을(를) 다시 생성하시겠습니까?"라고 표시됩니다: "동일한 액세스 권한을 가진 새 시크릿이 발급됩니다. 이전 시크릿은 작동이 중단됩니다." 에이전트가 여전히 사용 중이고 전환할 시간이 필요하다면 24시간 동안 이전 시크릿 유지를 체크하세요. 즉시 중단하려면 체크를 해제하세요.
새 시크릿 복사
다시 생성을 클릭하세요. 토큰 생성됨 대화 상자에 새 시크릿이 한 번 표시됩니다. 복사하여 에이전트나 시크릿 저장소를 업데이트한 후 저장했습니다를 클릭하세요.
다시 생성 규칙:
- 토큰을 생성한 사람만 다시 생성할 수 있습니다. 생성하지 않은 소유자나 관리자에게는 "토큰을 생성한 사람만 다시 생성할 수 있습니다. 취소는 가능합니다."라고 표시됩니다.
- 시크릿은 한 번만 다시 생성할 수 있습니다. 그 후 이전 행에는 "다시 생성된 시크릿으로 대체됨"이 표시되며 시크릿 다시 생성 옵션이 없습니다. 대신 새 토큰을 다시 생성하세요. 이전 시크릿으로 다시 시도하면 "이 토큰은 이미 다시 생성되었거나, 취소되었거나, 만료되었습니다. 대체 토큰을 사용하거나 새 토큰을 생성하세요."라는 메시지가 표시됩니다.
- 만료일은 변경되지 않습니다. 90일로 생성된 토큰은 원래 날짜에 만료됩니다. 이전 시크릿의 24시간 유지 기간이 만료일을 넘어가면 만료일에 중단됩니다.
- 워크스페이스가 활성 토큰 제한에 도달해도 다시 생성할 수 있습니다. 24시간 중첩 기간 동안에는 두 시크릿 모두 작동하며 활성 토큰으로 계산됩니다.
- 다시 생성하려면 워크스페이스가 Pro 플랜 이상이어야 합니다. 그렇지 않으면 시크릿 다시 생성 클릭 시 업그레이드 대화 상자가 열립니다.
토큰 취소
- 토큰 행의 ⋯ 메뉴를 열고 취소를 선택하세요.
- 토큰 취소로 확인하세요: "이 토큰을 사용하는 에이전트는 즉시 액세스 권한을 잃게 됩니다. 이 작업은 되돌릴 수 없습니다."
취소된 토큰은 워크스페이스의 활성 토큰 제한에서 즉시 제외됩니다.
만료
모든 토큰은 만료됩니다. 생성 시 수명(7일, 30일, 90일(기본값) 또는 1년)을 선택합니다. "만료 없음" 옵션은 없으므로 잊혀진 토큰이 영원히 유효할 수는 없습니다. 만료일 열에 날짜가 표시됩니다.
만료일 이후 모든 호출은 "이 토큰은 만료되었습니다. Integrations → AI agents & API에서 새 토큰을 생성하세요."를 반환합니다. 만료된 토큰은 갱신하거나 다시 생성할 수 없으므로 새 토큰을 생성해야 합니다.
IP 허용 목록
토큰은 에이전트가 실행되는 주소(예: CI 러너 또는 서버)로 제한할 수 있습니다. 마법사의 제한 단계에서 고급 → IP 허용 목록 아래에 설정합니다: "선택 사항. 줄당 하나의 주소 또는 범위; 그 외의 주소에서 오는 호출은 거부됩니다."
- IPv4 또는 IPv6 주소(
203.0.113.7) 또는 CIDR 형식의 범위(198.51.100.0/24)를 최대 20개까지 입력하세요. - 비워두면 모든 주소가 허용됩니다. 검토 단계에서 모든 주소로 표시됩니다.
- 다른 주소에서 호출하면 "이 토큰은 이 IP 주소에서 사용할 수 없습니다."가 반환됩니다.
- 주소나 범위가 아닌 항목은 거부됩니다: "value은(는) IP 주소나 범위가 아닙니다."
토큰이 작동하지 않는 이유
| 토큰에 표시되는 내용 | 발생한 상황 | 조치 방법 |
|---|---|---|
| 만료됨 | 수명이 다했습니다. | 새 토큰을 생성하세요. |
| "소유자에 의해 취소됨" | 생성한 사람이 취소했습니다. | 여전히 필요하다면 새 토큰을 생성하세요. |
| "관리자에 의해 취소됨" | 워크스페이스 소유자나 관리자가 취소했습니다. | 새 토큰을 생성하기 전에 이유를 문의하세요. |
| "취소됨: 소유자가 워크스페이스를 떠남" | 생성한 사람이 워크스페이스에서 제거되었습니다. 모든 토큰이 취소됩니다. | 워크스페이스에 남아 있는 사람이 새 토큰을 생성하세요. |
| "취소됨: 소유자 계정이 삭제됨" | 소유자가 Clevera 계정을 삭제했습니다. | 새 토큰을 생성하세요. |
| "다시 생성된 시크릿으로 대체됨" | 시크릿이 다시 생성되었습니다. | 새 시크릿을 사용하세요. |
| "취소됨: 공개 저장소에서 발견됨" | 공개 GitHub 저장소에서 발견되어 자동으로 취소되었습니다. | 저장소 기록에서 제거한 후 새 토큰을 생성하여 시크릿 저장소에 보관하세요. |
| "취소됨: 비정상적인 활동" | 몇 분 내에 거부된 요청이 많았습니다(10분 내 50회 이상). | 활동에서 시도 내용을 확인하고, 에이전트를 수정한 뒤 새 토큰을 생성하세요. |
| "취소됨: 토큰 재사용 감지됨" / "취소됨: 앱 연결 해제됨" | 연결된 앱에 적용되며 API 토큰과는 무관합니다. | 앱을 다시 연결하세요. |
| 모든 호출이 "에이전트 API는 이 워크스페이스 플랜에 포함되어 있지 않습니다. Pro 플랜 이상에서 사용 가능합니다."를 반환함 | 워크스페이스가 Pro, Business 또는 Custom 플랜에서 제외되었습니다. | Pro 플랜으로 업그레이드하세요. 워크스페이스가 Pro 플랜에서 제외된 경우를 참조하세요. |
비정상적인 활동
Clevera는 각 토큰의 급증하는 요청을 감시하며 워크스페이스 소유자에게 "token에 비정상적인 활동 감지" 알림을 보냅니다:
- 거부된 요청이 많음: 몇 분 내에 거부된 요청이 많으면 토큰이 취소됩니다. "몇 분 내에 거부된 요청이 많이 발생했습니다."
- 비정상적으로 많은 변경 사항: 몇 분 내에 변경 사항이 비정상적으로 많으면(10분 내 200회 이상의 쓰기 또는 20회 이상의 페이지 삭제) 10분 동안 쓰기가 일시 중지됩니다. 호출 시 "비정상적인 변경 급증으로 인해 이 토큰의 쓰기 작업이 일시 중지되었습니다. 워크스페이스 소유자에게 알림이 전송되었습니다."가 반환됩니다. 읽기 작업은 계속 작동합니다.
- 크레딧이 비정상적으로 빠르게 소모됨: 토큰은 24시간 동안 유료 작업을 시작할 수 없습니다. "몇 분 내에 비정상적으로 많은 크레딧을 사용하여 현재 유료 작업을 시작할 수 없습니다."
워크스페이스가 Pro 플랜에서 제외된 경우
AI agents & API는 Pro, Business 및 Custom 플랜에서 제공됩니다. 워크스페이스가 Starter 또는 Free 플랜으로 이동하면 페이지에 "AI agents & API는 Pro 플랜에 포함되어 있습니다"라고 표시됩니다: "Claude, ChatGPT 및 스크립트가 이 워크스페이스에서 작동하도록 업그레이드하세요. 기존 토큰과 앱은 그때까지 작동이 중단되지만, 여기에서 취소할 수는 있습니다."
- 토큰은 계속 나열되며 취소할 수 있지만, 모든 호출은
plan_locked으로 거부됩니다. - 시크릿 다시 생성을 클릭하면 업그레이드 대화 상자가 열립니다.
- Pro 플랜으로 다시 업그레이드하면 토큰이 다시 작동합니다. 삭제된 것은 없으며 토큰은 원래 날짜에 만료됩니다.