認証

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

API キー (推奨)

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

Authorization: Bearer sk-your-api-key

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 分、__Host-access_token クッキーに設定（API ホストのみ）
リフレッシュトークン: TTL 30 日、__Host-refresh_token クッキーに設定（API ホストのみ）

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

SAML SSO

エンタープライズテナントは、Google / マジックリンクでのサインインの代わりに SAML SSO(Okta、Entra ID などの IdP)を有効化できます。SAML の終端は WorkOS が担い、ai& 側は OAuth 風のリダイレクトとして扱います:

コンソールが GET /auth/login/workos にリダイレクトし、WorkOS AuthKit のサインイン画面へ移動します。組織やドメインは渡しません。
ユーザーがその画面で勤務先のメールアドレスを入力すると、WorkOS がメールドメインから SSO 接続を判定し、IdP へ移動します。
IdP からのリダイレクト後、GET /auth/callback/workos が結果をセッションに交換し、他のサインイン方式と同じ Cookie ベースのフローに合流します。

受け付けるのは、実際に SSO 接続を通ったサインインだけです。AuthKit 自身のパスワードやソーシャルログインで入った場合は、組織に登録済みのメールドメインであっても拒否します。また、メールアドレスが貴社の検証済みドメインのものであるときだけ受け付けます。そのため、SSO で統合されるのは、会社の検証済みドメインのアドレスを持つ既存アカウントだけです。

貴社から最初にサインインした人が ai& 上の組織を作成し、その組織の Admin になります。2 人目以降は同じ組織に Member として参加します。ai& 上でメンバーを除名しても、再サインインは止まりません。IdP 側でアカウントが有効なままだと、次の SSO サインインで再び追加されます。退職者などを確実に外すときは、IdP 側でもアカウントを無効化してください。

SSO を必須にしたメールドメインでは、Google と GitHub のサインインはコンソールの sso_required エラーに戻り、マジックリンクの送信は 403 を返します。いずれも SSO でのサインインを案内します。組織で SSO を有効化するには、担当営業にお問い合わせください。

組織コンテキスト

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

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

エラーレスポンス

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

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