ローカルで動かす

アプリを手元で動かすと、Keelson のログインがないため、ユーザー情報のヘッダー（X-Keelson-User-Id など）が付きません。keelson dev serve を使うと、Keelson と同じヘッダーを付けたうえで、利用者を切り替えながら動作を確かめられます。

2 つの動かし方

	keelson dev serve 経由	KEELSON_LOCAL_MODE=1（CLI なし）
利用者	名簿の誰にでも切り替えられる	固定の 1 人
ユーザー情報の渡し方	本番と同じヘッダー	SDK がテスト用データを返す（ヘッダーは付かない）
メンバー一覧・グループ（listMembers など）	名簿から返す（Directory API の有効化は不要）	名簿から返す
必要なもの	最新の Keelson CLI	最新の SDK

通常は keelson dev serve を使います。CLI を入れていない、または古い CLI しかないときは KEELSON_LOCAL_MODE=1 で起動します。どちらでも、アプリのコードは同じです。

keelson dev serve で起動する

-- のあとに、アプリのサーバーを起動するコマンドを書きます。

# Node.js
keelson dev serve -- node server.js

# Python
keelson dev serve -- uvicorn main:app --host 127.0.0.1 --port {port}

# Go
keelson dev serve -- go run .

• CLI がアプリ用の空いているポートを選び、環境変数 PORT で渡します。コマンド中の {port} もその番号に置き換わります。アプリは 127.0.0.1 のそのポートで待ち受けてください
• ブラウザでは http://localhost:5173/ を開きます。ポートは --port で変えられます
• CLI はアプリの手前に立ち、リクエストごとに選択中の利用者のヘッダー（X-Keelson-User-Id / X-Keelson-User-Email / X-Keelson-User-Name / X-Keelson-User-App-Perms）を付けます。本番と同じく、ブラウザの Cookie と Authorization ヘッダーはアプリへ届きません
• 起動すると、アプリの URL、現在の利用者、切り替え方が表示されます。Ctrl-C で止めると、アプリのサーバーも止まります

利用者を切り替える

方法	使い方
切り替えページ	ブラウザで http://localhost:5173/__keelson/dev を開き、利用者を選びます。開いている別のタブは、再読み込みするまで前の利用者のままです
X-Keelson-Dev-As ヘッダー	リクエストに X-Keelson-Dev-As: <利用者の ID> を付けると、そのリクエストだけその利用者になります。AI エージェントや curl での確認に使います
--as	keelson dev serve --as <利用者の ID> -- ... で、起動時の利用者を決めます

# 閲覧権限だけの利用者として API を呼ぶ
curl -H "X-Keelson-Dev-As: local-user-003" http://localhost:5173/api/items

名簿にない ID を指定するとエラーになります。

名簿ファイル

利用者の一覧（名簿）は JSON ファイルで用意します。次の順で探します。

• keelson dev serve: --users <ファイル> → ./.keelson/dev-users.json
• KEELSON_LOCAL_MODE=1: 環境変数 KEELSON_LOCAL_USERS_FILE → ./.keelson/dev-users.json

{
  "users": [
    { "id": "sample-tanaka", "email": "[email protected]", "name": "田中 太郎", "perms": ["view", "manage"] },
    { "id": "sample-sato", "email": "[email protected]", "name": "佐藤 花子", "perms": ["view"] }
  ]
}

項目	内容
id	利用者の ID。名簿の中で重複させません。本番の ID とは別の、読みやすい文字列でかまいません
email / name	メールアドレスと表示名。空文字も可
perms	["view"]（閲覧のみ）または ["view", "manage"]（管理権限あり）。X-Keelson-User-App-Perms の値になります
image_url	任意。プロフィール画像の URL

• 名簿の先頭で manage を持つ人が、既定の利用者になります
• 指定したファイルが無い・形が正しくないときは、起動時にエラーになります
• 名簿ファイルが無いときは、組み込みの 4 人（local-user-001 から local-user-004）を使います。keelson dev serve では、local-user-003 と local-user-004 は閲覧権限だけです
• 名簿を変えたら、起動し直してください

CLI なしで動かす（KEELSON_LOCAL_MODE=1）

アプリのサーバーを、環境変数 KEELSON_LOCAL_MODE=1 を付けて直接起動します。

KEELSON_LOCAL_MODE=1 node server.js

keelson dev serve --users <ファイル> で独自の名簿を使っているアプリは、直接起動するときも KEELSON_LOCAL_USERS_FILE=<同じファイル> を渡してください。CLI の有無で利用者の ID が変わらなくなります。

Identity SDK はヘッダーを読まず、固定の 1 人（名簿の先頭で manage を持つ人）を今の利用者として返します。名簿ファイルが無いときは、管理権限を持つテスト用ユーザー（local-user-001）になります。利用者は切り替えられません。ヘッダーを直接読むコードには、このテスト用データは適用されません。

今の利用者と権限を取得する（getRequestUser）

getRequestUser は、リクエストのヘッダーから今の利用者と、このアプリでの権限（perms）をまとめて返します。外部への通信はしません。本番と、上の 2 つの動かし方のどれでも同じコードで動きます。

import { getRequestUser } from "@keelsonhq/identity";

app.get("/admin", async (req, res) => {
  const user = await getRequestUser({ headers: req.headers }); // { id, email, name, perms }
  if (!user.perms.includes("manage")) return res.status(403).end();
  res.send(`${user.name ?? user.id} さん、こんにちは`);
});

from keelson import identity

user = identity.get_request_user(headers=request.headers)
if "manage" not in user.perms:
    ...  # 403 を返す

client, err := identity.New("") // 起動時に 1 回

// ハンドラの中で
user, err := client.GetRequestUser(identity.WithHeaders(r.Header))
if err != nil {
  http.Error(w, "unauthorized", http.StatusUnauthorized)
  return
}
canManage := slices.Contains(user.Perms, "manage")

ユーザー ID のヘッダーが無いときはエラーになります。perms は X-Keelson-User-App-Perms を分けたもので、ヘッダーが無ければ空です。日本語の表示名も正しく読み取れます。

本番では動かない

ローカル開発の仕組みは、Keelson にデプロイしたアプリでは動きません。

• デプロイ先で KEELSON_LOCAL_MODE が設定されていると、SDK はテスト用データを返さずにエラーにします。KEELSON_LOCAL_MODE を外してください
• keelson dev serve も、デプロイ先の環境では起動しません

関連ページ

• ログイン中のユーザー情報を使う
• Keelson SDK
• CLI リファレンス