認証

KUKAN API は 2 つの認証方式に対応しています。

ブラウザからのアクセスは Better Auth のセッション Cookie（HTTPS では __Secure- プレフィックス付き）で認証されます。ログイン後、通常の fetch で自動的に送信されます。

const res = await fetch('/api/v1/users/me', {
  credentials: 'include',
})

API トークン（Bearer 認証）

プログラムからのアクセスには API トークンを使用します。

トークンの発行

ユーザーメニュー → APIトークン画面、または API から発行できます。

curl -X POST https://your-kukan-site/api/v1/api-tokens \
  -H "Content-Type: application/json" \
  -H "Cookie: <session-cookie>" \
  -d '{"name":"my-script","expiresInDays":90}'

レスポンス:

{
  "id": "3f2c9a1e-...",
  "name": "my-script",
  "token": "kukan_xxxxxxxx...",
  "expiresAt": "2026-07-13T00:00:00.000Z",
  "created": "2026-04-14T00:00:00.000Z"
}

ステータスは 201 です。id は UUID です。expiresInDays は 1〜365 で、省略すると有効期限なしになります。

トークンの使用

Authorization: Bearer ヘッダーでトークンを送信します。

curl https://your-kukan-site/api/v1/users/me \
  -H "Authorization: Bearer kukan_xxxxxxxx..."

サイトが Basic 認証の裏にあると、Authorization ヘッダーは Basic 認証の資格情報で埋まります。その場合はトークンを X-KUKAN-API-Key ヘッダーで送ってください。REST API・MCP・CKAN 互換 API のどれでも使えます。

curl https://your-kukan-site/api/v1/users/me \
  -u "<basic-user>:<basic-password>" \
  -H "X-KUKAN-API-Key: kukan_xxxxxxxx..."

両方を送った場合は Authorization: Bearer が優先されます。

トークンの管理

# 一覧
curl https://your-kukan-site/api/v1/api-tokens \
  -H "Authorization: Bearer <token>"

# 失効
curl -X DELETE https://your-kukan-site/api/v1/api-tokens/<id> \
  -H "Authorization: Bearer <token>"

権限モデル

権限レベル	説明
公開（認証不要）	検索、公開データセットの閲覧
認証済み	自分の情報、非公開データセット（所属組織）
組織メンバー / 編集者 / 管理者	組織データの作成・編集・管理
カテゴリーメンバー / 編集者 / 管理者	カテゴリーへのデータセット追加・管理
システム管理者（sysadmin）	全ユーザー・組織・ジョブの管理

エラーコード

HTTP	意味
400	バリデーションエラー
401	未認証（ログインまたはトークンが必要）
403	権限不足
404	リソースが存在しない
409	競合（例: 同名リソースの重複）
429	リクエスト過多（例: AI 提案の回数上限）
503	一時的に利用不可