Callabo PAT 발급하기: API·CLI 개인 액세스 토큰 가이드

**PAT(Personal Access Token, 개인 액세스 토큰)**는 Callabo API, CLI와 MCP 클라이언트에서 사용자를 인증하는 비밀 값입니다. PAT로 수행한 작업은 토큰을 발급한 사용자의 권한으로 처리되므로 비밀번호와 같은 수준으로 보관하고, 더 이상 쓰지 않거나 노출이 의심되면 즉시 폐기하세요.

이 문서는 2026년 8월 Callabo 웹과 CLI 0.1.11 구현을 기준으로 작성했습니다. PAT는 로그인 세션 토큰과 수명·폐기 방식이 다르므로 아래 절차를 끝까지 확인하세요.

PAT의 권한과 워크스페이스 적용 범위 이해하기

현재 발급 화면에는 별도의 API scope 선택 항목이 없습니다. PAT는 발급한 사용자와 연결되며, 실제 API 접근 범위는 다음 조건을 모두 따릅니다.

• 토큰을 발급한 사용자가 현재 보유한 워크스페이스·팀·미팅 권한
• 대상 워크스페이스의 개인 액세스 토큰 사용 허용 설정
• 호출하려는 API 기능에 필요한 계약과 세부 permission
• MCP를 사용할 때는 별도의 MCP 사용 허용 설정

따라서 PAT를 발급했다고 모든 워크스페이스 데이터에 접근할 수 있는 것은 아닙니다. 사용자 권한이 줄어들거나 대상 워크스페이스가 PAT 사용을 끄면 같은 토큰의 요청도 차단됩니다. 역할과 permission은 팀원 관리 가이드를 참고하세요.

자동화에는 개인 계정의 광범위한 권한을 그대로 쓰기보다 필요한 권한만 가진 전용 사용자를 검토하고, 용도별로 PAT를 나누어 발급하세요. 토큰 이름과 설명에 담당 시스템과 사용 목적을 남기면 나중에 폐기 대상을 구분하기 쉽습니다.

워크스페이스의 PAT 사용 허용 상태 확인하기

1. Callabo 왼쪽 메뉴에서 대상 워크스페이스를 선택합니다.
2. 워크스페이스 설정으로 이동합니다.
3. 보안에서 개인 액세스 토큰 사용 허용을 찾습니다.
4. 해당 워크스페이스의 API에서 PAT를 써야 한다면 허용 상태인지 확인합니다.

이 항목은 워크스페이스 PAT 관리 permission이 있는 사용자에게만 표시됩니다. 설정이 보이지 않거나 바꿀 수 없다면 워크스페이스 관리자에게 요청하세요. 계약에 따라 보안 설정이 잠겨 있을 수도 있습니다. 다른 워크스페이스 설정은 워크스페이스 설정 가이드를 참고하세요.

사용하지 않음으로 바꾸면 그 워크스페이스 범위의 PAT API 호출이 차단됩니다. 토큰 자체는 개인 설정 목록에 남으며, PAT 사용이 허용된 다른 워크스페이스에서는 계속 동작할 수 있습니다.

개인 설정에서 PAT 발급하기

1. 왼쪽 아래의 사용자 프로필을 선택하고 내 설정으로 이동합니다.
2. 보안 카드의 개인 액세스 토큰 영역을 찾습니다.
3. 토큰 발급을 선택합니다.
4. 토큰을 구분할 이름을 입력합니다. 이름은 필수이며 최대 100자입니다.
5. 필요하면 설명에 용도와 담당 시스템을 입력합니다. 설명은 최대 255자입니다.
6. 유효기간에서 1주, 1개월, 6개월, 1년, 무제한 중 하나를 선택합니다.
7. 발급을 선택합니다.
8. 발급 직후 나타나는 PAT 원문을 복사해 안전한 비밀 저장소에 보관합니다.
9. 복사와 저장을 검증한 뒤 확인했습니다를 선택합니다.

기본 유효기간 선택값은 무제한입니다. 장기간 유지해야 하는 명확한 이유가 없다면 가능한 짧은 기간을 선택하고 만료 전에 교체하는 편이 안전합니다.

폐기되지 않은 활성·만료 PAT가 발급 한도에 함께 포함됩니다. 토큰 발급을 사용할 수 없거나 한도 메시지가 나타나면 쓰지 않는 토큰과 만료된 토큰을 먼저 폐기하세요.

1회 표시되는 PAT 원문 안전하게 보관하기

PAT 원문은 발급 성공 응답과 직후 화면에서 한 번만 확인할 수 있습니다. 확인했습니다를 선택하거나 창을 닫은 뒤에는 목록에서 원문을 다시 볼 수 없습니다. 서버에는 원문이 아니라 검증용 digest가 저장됩니다.

다음 위치에는 PAT를 남기지 마세요.

• Git 저장소와 코드·설정 예시
• 이슈, 메신저, 이메일과 문서 본문
• 명령줄 인자와 shell history
• 애플리케이션 로그, 분석 이벤트와 오류 보고
• 토큰이 보이는 화면 캡처와 녹화

CI/CD와 서버 자동화에서는 사용하는 플랫폼의 secret 저장소를 사용하세요. 로컬 MCP는 환경 변수나 클라이언트가 제공하는 secret 보관 기능을 사용하고, .env 파일은 버전 관리에서 제외합니다. 공개 문서에는 실제 형식의 토큰을 쓰지 말고 <발급한 PAT> 같은 자리표시자만 사용하세요.

토큰을 잃어버렸다면 복구를 시도하지 말고 기존 PAT를 폐기한 뒤 새 토큰을 발급합니다. 노출이 의심되면 먼저 폐기하고, 새 토큰으로 연결 대상을 교체한 뒤 관련 API 사용 기록을 확인하세요. 워크스페이스에서 제공하는 기록 범위는 감사로그 가이드를 참고할 수 있습니다.

Callabo CLI에서 PAT로 로그인하기

현재 CLI에서 PAT 로그인을 시작하는 명령은 다음과 같습니다.

callabo auth login --pat

명령을 실행하면 터미널에 Personal access token 입력 프롬프트가 나타납니다. 발급한 PAT를 붙여넣고 Enter를 누르세요. 입력값은 화면에 표시되지 않으며, CLI는 형식과 인증 상태를 확인한 뒤 접근 가능한 워크스페이스를 불러옵니다.

PAT 값을 callabo auth login --pat <발급한 PAT>처럼 명령 뒤에 붙이지 마세요. 현재 --pat는 토큰 값을 받는 옵션이 아니라 숨김 입력 모드를 여는 flag입니다. 명령줄에 비밀 값을 직접 넣으면 shell history나 프로세스 목록에 남을 위험도 있습니다.

로그인 후 접근 가능한 워크스페이스를 확인합니다.

callabo workspace ls

기본 워크스페이스를 지정하려면 다음 명령을 사용합니다.

callabo workspace default <workspace_slug>

CLI는 PAT 사용이 허용된 워크스페이스 가운데 접근 가능한 항목을 기본 대상으로 선택합니다. 대상이 없다면 기본 워크스페이스를 저장하지 않습니다. CLI 설치와 최신 명령은 Callabo CLI 공식 저장소를 확인하세요.

CLI 인증 상태 확인과 로그아웃 구분하기

저장된 PAT가 아직 유효한지 확인하려면 다음 명령을 실행합니다.

callabo auth refresh

일반 로그인에서는 access token을 갱신하지만, PAT 로그인에서는 새 토큰을 만들거나 만료를 연장하지 않고 현재 PAT가 유효한지만 검증합니다.

로컬 CLI에서 인증 정보를 지우려면 다음 명령을 실행합니다.

callabo auth logout

PAT 로그인 상태에서 auth logout은 시스템 keychain 또는 로컬 credential store의 인증 정보만 삭제합니다. 웹에서 발급한 PAT 자체는 폐기되지 않으며 다른 기기·자동화에서 계속 사용할 수 있습니다. 원격 사용까지 중단하려면 반드시 Callabo 웹의 개인 액세스 토큰 목록에서 폐기하세요.

CLI는 운영체제의 keychain을 우선 사용합니다. Linux에서 keyring backend가 없으면 ~/.config/callabo/credentials.json을 0600 권한으로 저장하지만, 공용 계정이나 공유 서버에서는 파일 접근 권한을 별도로 확인하세요.

만료된 토큰 확인하고 PAT 폐기하기

개인 액세스 토큰 목록에는 토큰 이름, 활성 또는 만료 상태, 만료일이나 유효기간 무제한, 설명이 표시됩니다. 만료된 PAT는 인증에 사용할 수 없지만 자동으로 목록에서 제거되지는 않습니다.

1. 내 설정 > 보안 > 개인 액세스 토큰으로 이동합니다.
2. 중단할 토큰의 이름, 상태와 설명을 확인합니다.
3. 폐기를 선택합니다.
4. 확인 창에서 다시 폐기를 선택합니다.
5. 해당 PAT를 사용하던 CLI, MCP와 자동화가 실패하는지 확인합니다.
6. 교체가 필요하면 새 PAT를 발급하고 각 연결의 secret을 갱신합니다.

폐기는 되돌릴 수 없습니다. 실행 중이던 요청의 결과까지 취소하는 기능은 아니므로, 노출 사고라면 연결 대상과 최근 작업을 함께 점검하세요. 토큰을 정기적으로 교체할 때는 새 토큰 연결 확인 후 기존 토큰을 폐기해 자동화 중단 시간을 줄일 수 있습니다.

PAT 인증 오류 해결하기

CLI가 PAT 형식을 거부할 때

• 최신 CLI를 설치한 뒤 callabo --version을 확인합니다.
• callabo auth login --pat만 실행하고 숨김 프롬프트에 원문을 붙여넣습니다.
• 앞뒤 공백이나 줄바꿈이 포함되지 않았는지 확인합니다.
• 원문을 잃어버렸다면 기존 토큰을 폐기하고 새로 발급합니다.

로그인은 되지만 워크스페이스가 보이지 않을 때

• 해당 워크스페이스의 멤버인지 확인합니다.
• 개인 액세스 토큰 사용 허용이 켜져 있는지 확인합니다.
• 사용자 역할에 호출하려는 기능의 permission이 있는지 확인합니다.
• callabo workspace ls로 실제 접근 가능한 목록을 다시 조회합니다.

만료 또는 폐기 뒤에도 연결이 남아 있을 때

• CLI에서 callabo auth logout으로 로컬 자격 증명을 지웁니다.
• 자동화와 MCP 클라이언트의 secret을 제거하거나 새 PAT로 교체합니다.
• 웹의 PAT 목록에서 대상 토큰이 더 이상 활성 상태가 아닌지 확인합니다.
• 계속 API 호출이 성공하면 토큰 이름, 폐기 시각과 요청 정보를 정리해 지원팀에 문의합니다.

MCP 연결이 목적이라면 PAT 발급 후 MCP 설정 가이드를 이어서 확인하세요.

지금 Callabo 시작하기

PAT 문제를 문의할 때 실제 토큰 원문을 보내지 마세요. 토큰 이름, 상태, 만료일, 워크스페이스, CLI 버전, 오류 문구와 발생 시각만 정리해 채널톡 또는 support@callabo.ai로 문의하세요.