인증 · Kisenon

Kisenon에는 두 가지 인증 방식이 있습니다:

웹 로그인 — 콘솔에서 NextAuth를 통한 Google 또는 GitHub OAuth.
API 키 — 모든 HTTP 클라이언트(keon 포함)가 Bearer 자격 증명으로 제시할 수 있는 nsk_… 토큰.

동일한 키로 CLI, CI, 그리고 일회성 curl 호출을 구동할 수 있습니다.

웹 로그인

kisenon.com을 열고 Sign in을 클릭하세요. Google 또는 GitHub를 선택합니다. NextAuth가 OAuth 절차를 처리한 다음, POST /v1/auth/exchange를 통해 제공자의 id 토큰을 컨트롤 플레인 JWT로 교환합니다. 이 cp 서명 JWT가 이후 모든 콘솔 요청이 지니는 자격 증명입니다.

JWT는 수명이 짧습니다 — 발급 후 대략 15분 뒤에 만료됩니다. 활성 상태인 동안에는 NextAuth가 현재 JWT를 POST /v1/auth/refresh에 다시 제시하여 백그라운드에서 이를 갱신하고 새 JWT를 발행합니다. 갱신 자격 증명은 JWT 자체이며, 로그인 시점으로부터 12시간 창 안에서 유효합니다. 그 창이 지나면 다음 요청은 로그인으로 리디렉션됩니다.

액세스

Google 또는 GitHub로 로그인하세요. 오픈 가입이 활성화되어 있으면, 새 계정은 즉시 사용할 수 있습니다: 첫 교환에서 사용자와 개인 조직이 생성되고, 곧바로 콘솔로 이동합니다.

온보딩하는 동안 액세스가 제한될 수 있습니다 — 운영자가 환경별로 켜고 끌 수 있는 킬 스위치입니다. 이것이 켜져 있으면, 로그인은 했지만 아직 활성화되지 않은 계정은 대기(pending) 상태에 머뭅니다: 콘솔은 이를 /pending으로 리디렉션하고, 컨트롤 플레인은 계정이 활성화될 때까지 제한된 API 호출에 403 alpha_pending으로 응답합니다. 구성된 로그인 허용 목록도 목록에 없는 계정을 세션이 발급되기 전에 403 email_not_allowed로 거부할 수 있습니다.

조직과 역할

신원은 조직 우선입니다. 모든 세션은 활성 조직과 그 안에서의 역할(예: owner 또는 member)을 지닙니다; cp JWT가 둘 다를 인코딩하며, 컨트롤 플레인은 매 갱신마다 역할을 다시 읽습니다. 개인 가입자는 자동으로 개인 조직을 받고, 초대받은 사용자는 첫 로그인 시 팀 조직에 들어갑니다.

둘 이상의 조직에 속해 있다면 콘솔(로그인 레이아웃 상단)의 조직 전환기에 역할 배지와 함께 조직 목록이 표시됩니다. 하나를 선택하면 /api/auth/switch-org로 POST되며, 이는 cp의 /v1/auth/switch-org로 프록시되어 새 조직으로 범위가 지정된 새 JWT를 세션에 이어 붙입니다. 전환 이후의 모든 콘솔 요청은 선택한 조직에서 동작합니다.

조직과 역할이 어떻게 작동하는지는 조직을, 팀원을 추가하는 방법은 초대를 참조하세요.

API 키

API 키는 nsk_ 접두사가 붙은 자격 증명입니다. 각 키는:

nsk_<random> 형식을 지니며 생성 시 한 번만 표시됩니다 — 저장 시 해시되므로 나중에 평문을 복구할 수 없습니다. 지금 저장하거나 교체하세요.
자신의 범위 안에서 사용자의 신원으로 동작합니다.
다른 키에 영향을 주지 않고 언제든지 폐기할 수 있습니다.

콘솔에서 키 발행하기

설정 → API 키에서 키를 발행합니다. 각 행은 키의 이름, id, 생성 날짜, 그리고 마지막 사용 시점을 보여줍니다. 생성 양식에는 네 개의 필드가 있습니다:

Name — 최대 64자의 레이블.
Capability — 아래를 참조하세요.
Scope — 아래를 참조하세요.
Expires (days) — 만료되지 않는 키는 비워 두세요.

제출하면 비밀 값이 한 번 노출됩니다. 대화 상자를 닫기 전에 복사하세요.

Capability는 키가 무엇을 할 수 있는지를 고릅니다:

read_write(기본값) — 전체 읽기 및 쓰기.
read — 읽기 전용; 변경을 일으키는 모든 호출에서 거부됩니다.
agent — 샌드박스를 구동할 수 있지만 쓰기 가능한 main 자격 증명은 가져올 수 없습니다. AI 에이전트에게 이 capability를 부여하여 프로덕션 main을 절대 건드리지 않고 브랜치에 대해 작동하도록 하세요. Agent-Safe Change Control을 참조하세요.

Scope는 키가 도달할 수 있는 대상을 고릅니다:

Organization(기본값) — 활성 조직 내의 모든 것.
특정 프로젝트 — 그 프로젝트로 제한됩니다; 다른 리소스에 대한 요청은 403 scope_insufficient을 받습니다. (브랜치 범위도 API를 통해 지원됩니다.)

키 생성에는 로그인된 브라우저 세션이 필요합니다 — nsk_ 키는 다른 키를 발행할 수 없습니다. 키는 자신을 폐기할 수 있지만, nsk_ 소지자는 자기 폐기만 할 수 있으며 다른 키는 삭제할 수 없습니다.

API를 통해

동일한 작업이 cp의 /v1/api-keys/ 엔드포인트에서 제공됩니다: 생성하려면 name, scope, capability를 POST하며, 응답은 평문 비밀 값을 한 번 담습니다.

IP 허용 목록

각 프로젝트는 CIDR의 네트워크 허용 목록을 지닐 수 있습니다. 목록이 설정되면, 목록에 있는 CIDR에서 시작된 연결만 프로젝트의 엔드포인트에 도달합니다; 시행은 깨우기 경로를 포함하므로, 목록에 없는 클라이언트는 일시 중지된 엔드포인트를 깨울 수도 없습니다. 빈 허용 목록은 IP 제한이 없음을 의미합니다 — 모든 소스가 허용됩니다.

CLI에서 목록을 관리하세요:

keon ip-allow add 203.0.113.0/24 --project prj_abc...
keon ip-allow list --project prj_abc...
keon ip-allow remove 203.0.113.0/24 --project prj_abc...

또는 API를 통해:

GET /v1/projects/{projectId}/ip-allow — 현재 규칙을 나열합니다.
POST /v1/projects/{projectId}/ip-allow — 규칙을 추가합니다. 본문은 {cidr, label, ttl_seconds?}이며; ttl_seconds는 선택 사항으로 규칙이 자체 만료되도록 만듭니다. 잘못된 형식의 CIDR은 422를 반환합니다.
DELETE /v1/projects/{projectId}/ip-allow/{cidr} — 규칙 하나를 제거합니다.
DELETE /v1/projects/{projectId}/ip-allow — 전체 목록을 재설정합니다.

시행은 프록시에서 이루어지며, 프록시는 약 30초마다 뷰를 갱신하므로 변경 사항은 수 초 내에 전파됩니다.

CLI 루프백 OAuth

keon login은 API 키를 붙여 넣으라고 요청하지 않습니다. 대신 루프백 OAuth 흐름을 실행합니다:

CLI가 임의의 높은 포트에서 로컬 HTTP 리스너를 시작합니다.
일회성 state 토큰과 루프백 리디렉션 URL과 함께 브라우저에서 https://kisenon.com/cli/authorize?...를 엽니다.
로그인하거나 (이미 로그인되어 있다면) Authorize를 클릭합니다.
콘솔이 수명이 짧은 코드와 함께 루프백 URL로 리디렉션합니다.
CLI가 POST /v1/cli/exchange에서 코드를 새로 발행된 API 키로 교환합니다.
키는 ~/.config/keon/credentials.json에 모드 0600으로 저장됩니다.

흐름이 끝나면 keon whoami가 키가 연결되었음을 확인합니다:

keon login
keon whoami

CLI는 OAuth 코드, state, 또는 제공자 측 토큰을 저장하지 않습니다; 오직 결과로 나온 API 키만 저장합니다. 그 키는 콘솔에서 언제든지 교체하거나 폐기할 수 있습니다.

로그아웃

keon logout은 서버에서 로컬 API 키를 폐기하고 자격 증명 파일을 제거합니다. 로그아웃 후에는 동일한 keon login 흐름이 새 키를 발행하며, 이전 자격 증명은 다시 활성화할 수 없습니다.

keon logout

콘솔 로그아웃은 브라우저 세션을 지우고 랜딩 페이지로 리디렉션합니다; CLI를 통해 발행한 API 키는 폐기하지 않습니다. 그러한 키는 설정 → API 키에서 개별적으로 폐기하세요.

임의 클라이언트에서의 Bearer 인증

HTTP를 구사하는 모든 클라이언트가 컨트롤 플레인에 접근할 수 있습니다:

curl -H "Authorization: Bearer $KISENON_API_KEY" \
  https://api.kisenon.com/v1/projects

bearer 토큰은 API 키(nsk_…)이거나 /v1/auth/exchange를 통해 발급된 cp 서명 JWT입니다. 조직 범위 엔드포인트에서는 둘이 동등합니다.

인증