認証

すべての API エンドポイントには認証が必要です。ai& は次の 2 つの方式に対応しています。

API キー (推奨)

Authorization ヘッダに API キーを指定します:

Authorization: Bearer sk-your-api-key

API キーは組織に紐づきます。各キーから対応する課金アカウントが自動的に解決されます。

注意

API キーが平文で表示されるのは作成時の一度きりです。安全な場所に保管してください。後から完全なキーを取得することはできません。

キーの形式

すべての API キーは sk- で始まります。

キーの管理

API キーは コンソール または管理 API から作成、一覧、更新、無効化できます:

操作	エンドポイント
キー一覧	GET /api/v1/keys
キー作成	POST /api/v1/keys
キー更新	PATCH /api/v1/keys/{key_id}
キー削除	DELETE /api/v1/keys/{key_id}

キー管理 API を呼び出す際は、X-Org-ID ヘッダに組織 ID を指定してください。

ターミナルからは、ai& CLI の aiand login でブラウザからサインインすると、キーの作成・保存・ローテーションを CLI が代行します。

JWT (セッション認証)

ブラウザベースのクライアントは、httpOnly クッキーに保存された JWT トークンで認証します。コンソール Web アプリで使用される方式であり、プログラムからの API アクセスには推奨しません。

• アクセストークン: TTL 15 分、access_token クッキーに設定
• リフレッシュトークン: TTL 30 日、refresh_token クッキーに設定

JWT は OAuth (Google / GitHub) またはマジックリンクのサインインフローで発行されます。

組織コンテキスト

API キーは組織に紐づいているため、API キーで認証する場合は組織が自動的に解決されます。

JWT 認証を使う場合は、X-Org-ID ヘッダで組織コンテキストを指定してください。

エラーレスポンス

ステータス	意味
401	認証情報が欠落しているか無効
402	課金アカウントのクレジット残高が不足
403	認証情報は有効だが権限が不足

エラーレスポンスの完全な形式は エラーコード を参照してください。