Client Tokens로 앱별 접근 관리하기

클라이언트 토큰이란

클라이언트 토큰은 고른 Msty Nexus 기기를 부르는 앱과 서비스가 쓰는 bearer 방식의 API 키입니다. 앱은 OpenAI나 Anthropic의 키 대신 이 토큰을 API 키 자리에 넣습니다.

문서의 첫 번째 원칙은 “클라이언트 하나에 토큰 하나”입니다. 그래야 접근을 누구 것인지 구분하고, 따로 제한하고, 따로 교체하고, 따로 폐기할 수 있습니다.

업무 예를 들면(설명을 위한 예입니다), 챗 앱, 코드 편집기 확장, 야간 자동화 스크립트에 토큰을 하나씩 따로 줍니다. 스크립트가 필요 없어지면 그 토큰만 폐기하고, 나머지 둘은 그대로 씁니다.

화면은 Console Administer 묶음의 Client Tokens입니다. Settings 문서는 토큰이 이제 별도 페이지로 옮겨졌다고 적었습니다.

요금제별 토큰 수

Nexus 요금 페이지 기준입니다.

요금제	클라이언트 토큰
Free	10개
Pro	25개
Enterprise	25개부터

토큰 만들기

1. Client Tokens를 엽니다.
2. 앱이 부를 기기를 고릅니다.
3. Add token을 고릅니다.
4. 앱이나 담당자를 알아볼 수 있는 이름을 붙입니다.
5. 쓸 수 있는 가장 좁은 역할을 고릅니다.
6. 지원되는 요청 한도나 토큰 예산 한도를 설정합니다.
7. 한 번만 나오는 전달 화면에서 토큰 원문을 복사합니다.

전달 화면을 닫으면 Nexus에는 해시만 남습니다. 원문을 잃어버렸다면 되찾을 방법은 없고, 토큰을 교체하거나 새로 만들어야 합니다.

이름은 Settings 문서가 Desktop Client, Raycast, Internal Dashboard 같은 예를 듭니다. 나중에 목록만 보고 어느 앱 것인지 알 수 있어야 합니다. 담당이 바뀌면 이름을 고칩니다.

역할 두 가지

역할	할 수 있는 일	줄 대상
Inference	지원되는 게이트웨이 경로를 부르고, 그 클라이언트에 필요한 상태만 읽습니다	모델만 쓰면 되는 일반 앱
Admin	관리 API에 닿을 수 있습니다	믿을 수 있는 운영자와 관리 도구

Free에서는 admin 토큰을 만들 수 없습니다. 앱이 모델 접근만 필요로 한다면 항상 inference 토큰을 쓰라고 문서는 권합니다.

토큰별 한도

지원되는 경우 토큰 하나에 다음을 제한할 수 있습니다.

• 쓸 수 있는 모델
• 동시 요청 수
• 대기 요청 수
• 하루 또는 한 달의 토큰 사용량

토큰 단위 제한은 Pro의 로컬 guardrail이나 Enterprise의 조직 정책과 보수적으로 합쳐집니다. 규칙은 두 가지입니다.

• 거부(deny) 규칙이 이깁니다.
• 적용되는 양수 한도 가운데 가장 낮은 값이 적용됩니다.

예를 들어(설명을 위한 예입니다) 토큰에는 동시 요청 8, 조직 정책에는 4가 걸려 있으면 4가 적용됩니다.

어느 한도가 어느 요금제에서 “지원되는 경우”에 해당하는지의 표는 공식 문서에는 설명이 없습니다.

토큰 교체(rotate)

교체는 토큰 자리를 하나 더 쓰지 않고 자격 증명만 바꿉니다. 순서가 중요합니다.

1. 교체를 실행합니다.
2. 새로 표시된 키를 앱에 넣습니다.
3. 그 뒤에 예전 값을 버립니다.

새 키도 한 번만 표시됩니다. 의도한 비밀 관리 도구나 앱 설정에 저장하기 전에는 전달 화면을 닫지 않습니다.

접속 주소

Client Tokens 화면은 고른 기기에서 쓸 수 있는 주소를 함께 보여 줍니다.

주소 종류	조건
루프백	같은 컴퓨터 안에서만
사설 네트워크	Private network access를 켰을 때
Access from anywhere	해당 엔드포인트를 설정했을 때

주소를 안다고 접근이 되는 것은 아닙니다. 앱은 어떤 주소로 접속하든 Nexus 토큰을 API 키로 보내야 합니다.

Access from anywhere도 로컬·사설 네트워크 접근과 같은, 그 기기에서 발급한 클라이언트 토큰을 씁니다. 이 기능을 켠다고 엔드포인트 전용 키가 따로 생기지 않습니다. 설정과 보안 안내는 Fleet에 있습니다.

토큰 폐기(revoke)

다음 경우에 폐기합니다.

• 클라이언트를 없앨 때
• 기기를 잃어버렸을 때
• 담당이나 소유가 바뀔 때

폐기는 그 토큰에만 영향을 줍니다. 제공업체 자격 증명이 드러나거나 바뀌지 않습니다. 이것이 제공업체 키를 앱마다 복사해 두는 방식과의 가장 큰 차이입니다. 키를 직접 나눠 줬다면 한 곳에서 새어 나갔을 때 키 자체를 바꾸고 모든 앱을 다시 설정해야 합니다.

토큰이 거부될 때

Troubleshooting 문서의 안내입니다.

증상은 UNAUTHORIZED 오류, 앱이 토큰이 없다고 알리는 경우, 게이트웨이 클라이언트가 인증 오류를 받는 경우입니다.

1. 클라이언트 토큰을 새로 만듭니다.
2. 앱의 API 키를 새 값으로 바꿉니다.
3. 앱이 허용된 토큰 헤더 가운데 하나로 보내는지 확인합니다. 헤더 형식은 게이트웨이 API에 있습니다.
4. 앱을 옮긴 뒤 예전 토큰을 폐기합니다.

가장 흔한 착각은 제공업체 API 키를 Nexus 키 자리에 넣는 것입니다. 제공업체 키는 Nexus API 키가 아닙니다. 앱은 로컬 Nexus 토큰으로 Nexus에 인증합니다.

Troubleshooting 문서는 토큰을 만드는 곳을 Settings > Client Tokens로 적고, Settings 문서와 Client Tokens 문서는 별도의 Client Tokens 페이지로 적습니다. 화면에 보이는 쪽을 따르면 됩니다.

저장 방식

Security 문서가 밝힌 내용입니다.

• 관리되는 클라이언트 토큰은 SQLite에 해시로 저장됩니다.
• 원문은 만들 때 한 번만 돌려줍니다.
• 토큰 목록과 조회 응답은 정보와 표시용 접두어만 보여 줍니다.
• Nexus 데스크톱 앱 자신의 로컬 토큰은 운영체제 키체인에 저장됩니다.

토큰은 앱을 Nexus에 인증하는 데만 쓰이고, 온라인 제공업체나 로컬 런타임으로 전달되지 않습니다.

참고한 문서

• Nexus 문서: Client Tokens
• Nexus 문서: Settings
• Nexus 문서: Security
• Nexus 문서: Troubleshooting
• Msty Nexus 요금