認証

/api/v1 配下のすべてのエンドポイントは（一部の公開エンドポイントを除き）認証が必要です。認証方法は 3 つあり、呼び出し元に応じて使い分けます。

方法	資格情報	利用者	スコープ
Session cookie	サインイン時に発行される Better Auth セッション	Web アプリ（ブラウザ）	制限なし
Personal Access Token	`spantail_pat_…`（Bearer トークン）	スクリプト、CLI、MCP サーバー	`read` / `write` / `admin`
Agent Access Token	`spantail_aat_…`（Bearer トークン）	AI エージェント、取り込み専用	なし（取り込み専用）

サインイン・サインアップ・パスワードリセットのエンドポイント自体は /api/auth 配下にあります。下の認証エンドポイントを参照してください。

Web アプリはユーザーのサインイン時に発行される Better Auth のセッション cookie で認証します（サインインを参照）。サインアウトで破棄されます。ブラウザから自動送信されるため、設定は不要です。セッションはスコープで制限されません。サインイン済みのユーザーは、その権限が許すことはすべて実行できます。

一部のエンドポイントは セッション専用 で、API トークンを拒否し対話的セッションを要求します。これらはプロフィールと資格情報の管理操作（アカウント設定の更新、アバターのアップロード、Personal Access Token の管理）です。アカウントとトークンを参照してください。

Personal Access Tokens

Personal Access Token（PAT）は、プログラムからのアクセスのためにあなたとして動作します。 Settings → Account → API tokens（または tokens API）から作成し、Bearer トークンとして送ります。

curl "https://<your-instance>/api/v1/work-entries?workspaceId=wrk_demo" \
  -H "Authorization: Bearer spantail_pat_yourtoken"

PAT は接頭辞 spantail_pat_ に続く 43 文字の URL セーフな base64（32 バイトの乱数）です。保存されるのは SHA-256 ハッシュのみで、平文は作成時に 一度だけ 表示され、その後は取得できません。

スコープ

すべての PAT は 1 つ以上のスコープを持ちます。トークンが持たないスコープを必要とするリクエストは 403 insufficient_scope で失敗します。スコープは累積的で、write は read を含みません。必要なスコープはそれぞれ付与してください。

スコープ	バッジ	付与する権限
`read`	scope: read	読み取り: リソース・統計・レポートの一覧と取得。
`write`	scope: write	呼び出し元自身のリソース（作業エントリなど）の作成・更新・削除。
`admin`	scope: admin	呼び出し元のロールが許す管理操作（ワークスペース・メンバー管理など）。

各エンドポイントのページは、必要なスコープをこれらのバッジで示します。スコープはトークンが試行できる範囲を広げるだけで、その背後のユーザーが本来持たない権限を与えることはありません。セッションでの呼び出しはスコープを完全に無視します。

Agent Access Tokens

Agent Access Token（AAT）は、単一のエージェントに紐づく 取り込み専用 の資格情報です。接頭辞 spantail_aat_ に続く 43 文字の URL セーフな base64 です。AAT はスコープを持たず（その能力は構造的に「このエージェント活動を取り込む」こと）、エージェントの所有者の代理として動作します。

AAT は通常のユーザールートでは拒否されます。エージェント取り込み以外の /api/v1 エンドポイントに提示すると 403 forbidden（“Agent tokens can only ingest agent entries”）を返します。エージェント取り込みに記載された取り込みエンドポイントに対してのみ使用してください。

無効化されたアカウント

インスタンス管理者がアカウントを無効化すると、ただちに完全にロックアウトされます。

セッションは無視され、すべての認証ルートが匿名の呼び出し元として 401 を返します。
Personal Access Token は 401（“This account is disabled”）で拒否されます。
所有者が無効化された Agent Access Token も同様に拒否されます。無効化・アーカイブされたエージェントのトークンも拒否されます。

アカウントを再度有効化すると、セッションとトークンは復活します。

認証エンドポイント

サインイン・サインアップ・パスワード復旧は、Better Auth が /api/v1 ではなく /api/auth 配下で処理します。これらはセッション cookie を設定または破棄します。以下のフィールドは代表的なものです。Better Auth はここに記載していない追加オプションも受け付けます。

サインイン

POST /api/auth/sign-in/email public

メールアドレスとパスワードで認証し、セッション cookie を設定します。無効化されたアカウントは 403 で拒否されます。

リクエストボディ

フィールド	型	必須	説明
`email`	string	はい	アカウントのメールアドレス。
`password`	string	はい	アカウントのパスワード。

curl
Response

curl -X POST "https://<your-instance>/api/auth/sign-in/email" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{ "email": "ana@example.com", "password": "correct horse battery staple" }'

{
  "user": {
    "id": "usr_ana",
    "name": "Ana",
    "email": "ana@example.com"
  },
  "token": "..."
}

サインアップ

POST /api/auth/sign-up/email public

新しいメール/パスワードのアカウントを登録します。インスタンスにユーザーが 1 人でも存在すると、公開サインアップは閉じられます。 オンボーディングは管理者主導（招待または直接作成）のため、ユーザーが既に存在する場合このエンドポイントは 403 forbidden（“Public sign-up is disabled; ask an instance admin for an invitation”）を返します。

したがって、これは新規インスタンスのブートストラップにのみ使えます。最初に登録されたユーザーがインスタンスを取得し、その管理者になります（メールは検証済みとして扱われます）。それ以降の新規メンバーは招待または管理者作成のアカウントで参加します。

リクエストボディ

フィールド	型	必須	説明
`name`	string	はい	表示名。
`email`	string	はい	アカウントのメールアドレス。
`password`	string	はい	アカウントのパスワード（8 文字以上）。

サインアウト

POST /api/auth/sign-out session only

現在のセッション cookie を破棄します。ボディはありません。

パスワードリセットの要求

POST /api/auth/request-password-reset public

セルフサービスのパスワード復旧を開始します。メールがアカウントに属していれば、リセットリンクが送信されます。アカウントの有無にかかわらずレスポンスは同一なので、登録済みのアドレスを明かしません。配信はインスタンスのメール設定でゲートされ、メールが無効な場合は何も送信せず、管理者への連絡を案内します。（レガシーの別名 POST /api/auth/forget-password も同じ動作です。）

リクエストボディ

フィールド	型	必須	説明
`email`	string	はい	アカウントのメールアドレス。

curl -X POST "https://<your-instance>/api/auth/request-password-reset" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@example.com" }'

パスワードのリセット

POST /api/auth/reset-password public

リセットメールのトークンを使って復旧を完了し、新しいパスワードを設定します。リセットすると、そのアカウントの他のすべてのアクティブなセッションが無効化されます。

リクエストボディ

フィールド	型	必須	説明
`token`	string	はい	リセットリンクのトークン。
`newPassword`	string	はい	新しいパスワード（8 文字以上）。

ソーシャルサインイン

POST /api/auth/sign-in/social public

OAuth サインインを開始し、リダイレクト先となるプロバイダの認可 URL を返します。利用可能なプロバイダはインスタンス管理者が設定します。Google と GitHub がサポートされており、有効化されていないプロバイダはルートを持たず、サインインに使えません。

参加要件は引き続き適用されます。新規のソーシャルアカウントは、招待されている場合（プロバイダで検証済みのメールが保留中の招待と一致する場合）か、Google で許可された自己参加ドメインに属する場合にのみサインインできます。それ以外は拒否されます。

リクエストボディ

フィールド	型	必須	説明
`provider`	string	はい	`google` または `github`。
`callbackURL`	string	いいえ	サインイン成功後の戻り先。

OAuth コールバック

GET /api/auth/callback/:provider public

ユーザーが認可した後、プロバイダがリダイレクトする戻り先です。Better Auth が交換を完了し、アカウントを作成またはリンクし、セッション cookie を設定します。これを直接呼び出すことはありません。ブラウザがここにリダイレクトされます。

認証

Session cookie

Personal Access Tokens

スコープ

Agent Access Tokens

無効化されたアカウント

認証エンドポイント

サインイン

サインアップ

サインアウト

パスワードリセットの要求

パスワードのリセット

ソーシャルサインイン

OAuth コールバック