> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK 認証

`query()` と `QoderSDKClient` は、SDK から `qodercli` を起動する際に認証設定が必要です。スクリプト、CI、ホストアプリケーションでは、Personal Access Token (PAT) を環境変数で注入する方法を推奨します。

ローカルマシンで `qodercli` にログイン済みの場合は、ローカルのログイン状態を再利用することもできます。

<div id="pat-の取得" />

<div id="patの取得" />

## PAT の取得

[qoder.com/account/integrations](https://qoder.com/account/integrations) で Personal Access Token を生成します:

1. Qoder アカウントにサインイン
2. **Account → Integrations** ページを開く
3. 新しい PAT を作成し、必要に応じて有効期限とスコープを選択
4. 生成後、**すぐにコピー**してください — ページを閉じると値を再表示できません。紛失した場合は再発行が必要です

> 1 つのアカウントで複数の PAT を発行できます。環境 (ローカルスクリプト、CI、本番サービス) ごとに別々のトークンを発行すると、個別に失効させやすくなります。

<div id="デフォルト環境変数から-pat-を読み取る" />

<div id="デフォルト環境変数からpatを読み取る" />

## デフォルト環境変数から PAT を読み取る

デフォルトの環境変数名は `QODER_PERSONAL_ACCESS_TOKEN` です。

```bash theme={null}
export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
```

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env, query

options = QoderAgentOptions(auth=access_token_from_env())

async for message in query(
    prompt="用一句话总结当前目录的项目用途。",
    options=options,
):
    print(message)
```

<div id="カスタム環境変数から-pat-を読み取る" />

<div id="カスタム環境変数からpatを読み取る" />

## カスタム環境変数から PAT を読み取る

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

options = QoderAgentOptions(auth=access_token_from_env("MY_QODER_PAT"))
```

`options.env` とプロセスの環境変数の両方に同名の変数が設定されている場合、SDK は `options.env` の値を優先的に読み取ります。

<div id="pat-を直接渡す" />

<div id="patを直接渡す" />

## PAT を直接渡す

ホストアプリケーションがシークレット管理サービス、ログイン状態、またはバックエンド API から PAT を取得済みの場合は、直接渡すことができます。トークンのリテラルをソースコードに書かないでください。

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token

token = read_token_from_secret_manager()
options = QoderAgentOptions(auth=access_token(token))
```

<div id="qodercli-のログイン状態を再利用する" />

<div id="qodercliのログイン状態を再利用する" />

## qodercli のログイン状態を再利用する

ローカルマシンで `qodercli` のログインが完了している場合、SDK に CLI のローカルログイン状態を読み取らせることができます。

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())
```

<div id="認証失敗コールバック" />

## 認証失敗コールバック

リモートがトークンを拒否した場合、トークンの有効期限切れ、または CLI が認証エラーで終了した場合は、`on_auth_expired` を使って再ログインまたはトークン更新フローをトリガーできます。各 SDK セッションで最大 1 回トリガーされます。

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

def show_sign_in_required() -> None:
    print("認証が失効しました。再度ログインしてください。")

options = QoderAgentOptions(
    auth=access_token_from_env(),
    on_auth_expired=show_sign_in_required,
)
```

SDK は PAT を自動更新しません。新しいトークンを取得した後は、新しいセッションを作成し、新しい `auth` 設定を渡す必要があります。

<div id="エラー" />

## エラー

* 認証設定が未指定: `AuthNotConfiguredError`、`code == "auth_not_configured"`。
* 環境変数が未設定: `AuthAccessTokenEnvVarError`、`code == "auth_access_token_env_var_not_configured"`。

<div id="ベストプラクティス" />

## ベストプラクティス

* 本番環境と CI では環境変数またはシークレット管理サービスを優先し、トークンをハードコードしないでください。
* トークンをログ、エラーオブジェクト、テストスナップショットに書き込まないでください。
* 自動化環境では PAT の使用を推奨し、ローカルの `qodercli` ログイン状態への依存は避けてください。
* ユーザー向けアプリケーションでは `on_auth_expired` を登録し、認証失敗を明確なログインプロンプトに変換してください。