# 認証

Source: https://aiand-docs-staging.pages.dev/ja/authentication/

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

## API キー (推奨)

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

```http
Authorization: Bearer sk-your-api-key
```

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

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

### キーの形式

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

### キーの管理

API キーは [コンソール](https://console.aiand.com) または管理 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](/ja/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 風のリダイレクトとして扱います:

1. コンソールが `GET /auth/login/workos` にリダイレクトし、WorkOS AuthKit のサインイン画面へ移動します。組織やドメインは渡しません。
2. ユーザーがその画面で勤務先のメールアドレスを入力すると、WorkOS がメールドメインから SSO 接続を判定し、IdP へ移動します。
3. 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`      | 認証情報は有効だが権限が不足         |

エラーレスポンスの完全な形式は [エラーコード](/ja/errors/) を参照してください。