Skip to main content
基本概念

SDK 認証

各 SDK セッション（TypeScript の query()、Python の query() / QoderSDKClient）には認証方式を1つ設定する必要があります。同一セッションで選べるのは1つだけです：
認証方式表す ID用途
Personal Access Token（PAT）Qoder ユーザーユーザーの権限とデータを必要とするスクリプト、CI、ホストアプリケーション
Service Account組織のワークロード個人アカウントに依存しないバックエンドサービス、CI、定期ジョブ
ローカル qodercli セッション現在サインイン中のユーザーQoder にサインイン済みの開発者ワークステーション

PAT を使用する

PAT は Qoder ユーザーを表します。そのユーザーの権限やデータにアクセスする必要がある自動化で使用します。

PAT を取得する

Qoder Account Integrations で PAT を作成します：
  1. Qoder にサインインします。
  2. Account → Integrations を開きます。
  3. 必要な権限と有効期限を選択して PAT を作成します。
  4. 生成された値をすぐにコピーします。ページを閉じると再表示できません。
個別にローテーションまたは失効できるよう、ローカルスクリプト、CI、本番環境で別々の PAT を作成してください。

環境変数から PAT を読み取る

export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"

import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize the current workspace.',
  options: {
    auth: accessTokenFromEnv(),
  },
});
この関数はデフォルトで QODER_PERSONAL_ACCESS_TOKEN を読み取ります。カスタム変数名を使う場合： 
auth: accessTokenFromEnv('MY_QODER_PAT')
options.env とプロセス環境に同名の変数がある場合、SDK は options.env の値を優先します。

PAT を直接渡す

信頼できるバックエンドが PAT を取得済みの場合は、直接渡せます： 
import { accessToken, query } from '@qoder-ai/qoder-agent-sdk';

const token = await readTokenFromSecretManager();
const q = query({
  prompt: 'List the most recently modified files.',
  options: {
    auth: accessToken(token),
  },
});
SDK は PAT を自動更新しません。PAT が無効になった後は、有効な PAT を取得して新しい SDK セッションを作成してください。

Service Account を使用する

はじめに、Qoder の組織管理者に Service Account の作成、アプリケーションに必要な権限の付与、Key の発行を依頼します。Key はシークレット管理サービスに保存し、信頼できるバックエンドプロセスまたは CI ジョブだけに渡してください。

Service Account Key を直接渡す

信頼できるバックエンドがシークレット管理サービスから Key を取得済みの場合は、直接渡せます： 
import { query, serviceAccount } from '@qoder-ai/qoder-agent-sdk';

// Get the Service Account key from the host's secret manager adapter.
const serviceAccountKey = await readSecret('qoder-service-account-key');

const q = query({
  prompt: 'Explain the purpose of this project in one sentence.',
  options: {
    auth: serviceAccount({ serviceAccountKey }),
    cwd: process.cwd(),
  },
});
呼び出し側は serviceAccount({ serviceAccountKey })（TypeScript）/ service_account(service_account_key=...)（Python）で Key をセッションに渡します。SDK と qodercli がセッション用の短期 Service Account Token（SAT）を取得・更新します。 
シークレット管理サービス
     |
     | Service Account Key
     v
呼び出し元が Key を取得
     |
     | serviceAccount({ serviceAccountKey })
     v
SDK が qodercli を起動して短期 SAT を取得
     |
     `----> SAT でセッションリクエストを認証
SDK は Key と SAT を現在のセッションで使用します。新しいセッションを作成するときは、呼び出し元が Key をもう一度渡します。Key はシークレット管理サービスから読み取り、Key の値をソースコード、ブラウザバンドル、モバイルアプリ、ログ、テストスナップショットに入れないでください。

ホストが SAT を提供して更新する

SDK を組み込むホストアプリケーションが SAT の交換を担う場合は、fetch コールバック形式（TypeScript の serviceAccount({ fetchServiceAccountToken })、Python の service_account(fetch_service_account_token=...)）を使います。Service Account Key はホストプロセス内に留まり、qodercli はホストのコールバックから SAT を受け取ります。 このコールバックはホストが実装します。qodercli は SAT が必要になるたびに呼び出し、ホストはリクエストごとに Token exchange API を呼んで、レスポンス内の新しい SAT を qodercli に返します。 
qodercli
     |
     | SAT をリクエスト
     v
SDK ホスト内の fetchServiceAccountToken コールバック
     |
     | ホストが管理する Service Account Key で Token exchange を呼び出す
     v
Qoder Token exchange
     |
     `----> 短期 SAT を qodercli に返す
次の例は、ホスト内で exchange を行う完全な処理を示します： 
import {
  query,
  serviceAccount,
  type ServiceAccountTokenResult,
} from '@qoder-ai/qoder-agent-sdk';

// Get the Service Account key from the host's secret manager adapter.
const serviceAccountKey = await readSecret('qoder-service-account-key');
// Example: select the scopes used for model listing and inference.
const serviceAccountScopes = ['models.read', 'chat.completions'];

async function fetchServiceAccountToken(): Promise<ServiceAccountTokenResult> {
  const response = await fetch(
    'https://openapi.qoder.sh/api/v1/serviceToken/exchange',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${serviceAccountKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        grant_type: 'client_credentials',
        audience: 'qoder',
        scope: serviceAccountScopes.join(' '),
        ttl_seconds: 3600,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Unable to obtain a Qoder SAT: HTTP ${response.status}`);
  }

  const result = (await response.json()) as {
    access_token: string;
    expires_in?: number;
  };

  return {
    token: result.access_token,
    expiresAt:
      result.expires_in === undefined
        ? undefined
        : Date.now() + result.expires_in * 1000,
  };
}

const q = query({
  prompt: 'Summarize the current deployment configuration.',
  options: {
    auth: serviceAccount({ fetchServiceAccountToken }),
  },
});
scope とコールバック戻り値は次のように設定します：
  • SAT を取得するときに、SAT に含める scope を指定します。たとえば、モデル一覧を取得して推論 API を呼び出す場合は、models.read chat.completions を指定します。
  • Token exchange で取得した SAT をコールバック結果に設定します。SAT の有効期限も指定できます。
  • 有効な SAT を取得できない場合は null（Python では None）を返すか例外を投げ、現在のセッションを明確に失敗させます。

ローカルのサインインを再利用する

ワークステーションが qodercli ですでにサインイン済みの場合、SDK は同じセッションを使用できます。この方式は開発者ワークステーション向けであり、ステートレスな CI や本番サービスには適していません。 
import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize the current workspace.',
  options: {
    auth: qodercliAuth(),
  },
});

認証失敗コールバック

リモート側が token を拒否した、token が期限切れになった、CLI が認証エラーで終了した場合は、onAuthExpired（TypeScript）/ on_auth_expired（Python）で再ログインや token 交換フローをトリガーできます。SDK セッションごとに最大1回発火します。 
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

def show_sign_in_required() -> None:
    print("Authentication has expired. Please sign in again.")

options = QoderAgentOptions(
    auth=access_token_from_env(),
    on_auth_expired=show_sign_in_required,
)
SDK は PAT を自動更新しません。新しいトークンを取得した後は、新しい auth 設定で SDK セッションを作成してください。

認証エラー

Python SDK の認証設定エラーは code 付きの例外を送出します：
  • 認証設定がない場合：AuthNotConfiguredError、code == "auth_not_configured"。
  • PAT の環境変数がない場合：AuthAccessTokenEnvVarError、code == "auth_access_token_env_var_not_configured"。
  • Service Account Key の環境変数がない場合：AuthServiceAccountEnvVarError、code == "auth_service_account_env_var_not_configured"。

ベストプラクティス

  • 本番環境と CI ではシークレット管理サービスから認証情報を提供し、認証情報をソースコードに書き込まないでください。
  • PAT、Service Account Key、SAT をログ、エラーオブジェクト、デバッグ出力に書き込まないでください。
  • 自動化環境では PAT または Service Account を明示的に設定し、ローカルの qodercli サインインに依存しないでください。
  • ユーザー向けアプリケーションでは認証失効コールバックを登録し、認証失敗を明確なサインイン案内に変換してください。
  • 認証情報を更新またはローテーションした後は、新しい SDK セッションを作成し、認証に失敗したセッションを再利用しないでください。
クイックスタート
基本概念
会話とセッション
ツールと拡張機能
制御と安全性
リファレンス
SDK 認証 - Qoder