인증 · Kisenon

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

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

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

웹 로그인

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

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

알파 기간 동안의 액세스

로그인은 제한되어 있습니다. 알파 허용 목록에 있는 이메일만 교환을 완료할 수 있습니다 — 목록에 없는 계정은 /v1/auth/exchange로부터 403 email_not_allowed를 돌려받고 세션을 전혀 받지 못합니다. 로그인은 했지만 아직 승인되지 않은 허용 목록 계정은 대기(pending) 상태에 머뭅니다. 콘솔은 이들을 /pending으로 리디렉션하고, 컨트롤 플레인은 운영자가 계정을 승인할 때까지 제한된 API 호출에 403 alpha_pending으로 응답합니다. 신청은 알파 액세스를 참조하세요.

조직과 역할

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

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

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

API 키

API 키는 조직 범위의 자격 증명입니다. 각 키는:

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

콘솔의 설정 → API 키에서 키를 관리합니다. 각 행은 키의 이름, id, 생성 날짜, 그리고 마지막 사용 시점을 보여줍니다. 생성은 이름을 받고 비밀 값을 한 번 노출하며, 폐기와 이름 변경은 인라인으로 이루어집니다.

범위와 권한

컨트롤 플레인은 각 키를 두 가지 방식으로 범위 지정합니다:

범위 종류 — org, project, 또는 branch. 조직 범위 키는 조직 내 모든 것에 도달하고, 프로젝트 또는 브랜치 범위 키는 지정된 프로젝트나 브랜치로 제한되며, 그 외 리소스에 대한 요청은 403 scope_insufficient을 받습니다.
권한 — read 또는 read_write. read 키는 변경을 일으키는 모든 호출에서 거부됩니다.

오늘날 콘솔에서 생성되는 키는 read_write 권한의 조직 범위입니다 — 아직 UI에 범위 선택기가 없습니다. 더 좁은 프로젝트/브랜치 범위와 read 권한은 cp의 /v1/api-keys/ 엔드포인트에 scope와 capability를 직접 POST하여 사용할 수 있습니다.

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.test.kisenon.com/v1/projects

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

인증