テーマ
API 認証
API 呼び出しに必要な認証ヘッダー、テナント指定、401 と 403 エラーの確認方法を説明します。
対象読者
開発者
前提
- 連携先テナントの 認証テナント ID（
authTenantId）を管理者から入手していること - 利用する認証方式に応じて、ユーザーセッションまたはアクセストークンを用意していること
知っておくこと
acomo API は Bearer 認証 と テナントヘッダー の組み合わせが必須です。ブラウザのフロントエンドも同じヘッダーを付与してバックエンドを呼び出します。
| ヘッダー | 例 | 説明 |
|---|---|---|
Authorization | Bearer eyJhbG... | acomo のサインインで取得したセッション JWT、または アクセストークン |
x-tenant-id | your-tenant-id | 認証テナント ID（サインイン URL の authTenantId と同じ値） |
認証方式の選び方
| 方式 | 向いている用途 |
|---|---|
| ユーザーセッション | ブラウザ拡張、社内ツール（ユーザーがサインインする） |
| アクセストークン | サーバー間バッチ、外部システム（ユーザー操作なし） |
アクセストークンは「認証」画面の アクセストークン タブで発行します。トークンには スコープ（例: Model:read）が付き、不足すると 403 になります。
ユーザーセッションを自前アプリで扱う
自前のフロントエンドやサーバーからユーザーをサインインさせる場合は、@acomo/client の認証ヘルパーを使います。サインイン・トークン更新・サインアウトはすべて acomo の API で完結し、アプリ側で認証基盤の SDK を組み込む必要はありません。
typescript
import { createAcomoAuth, createWebAuthStorage } from '@acomo/client'
const auth = createAcomoAuth({
apiUrl: 'https://YOUR_ACOMO_HOST', // /api/v1 は含めない
authTenantId: 'YOUR_AUTH_TENANT_ID',
storage: createWebAuthStorage(window.sessionStorage), // 既定はメモリ（リロードで失われる）
onSessionExpired: () => location.assign('/signin'),
})
await auth.signIn({ email, password })
// Authorizationとx-tenant-idは自動で付与される
const response = await auth.fetch('/my/processes')
if (!response.ok) {
throw new Error(`listMyProcesses failed: ${response.status}`)
}
const { processes } = await response.json()
await auth.signOut()| メソッド | 内容 |
|---|---|
signIn({ email, password }) | メールアドレスとパスワードでサインインし、セッションを保存します |
getAccessToken() | 有効なアクセストークンを返します。期限が近ければ自動で更新します |
fetch(path, init) | 認証ヘッダー付きで API を呼び出します（401 のときは 1 度だけ更新して再試行） |
restore() | 保存済みセッションを読み直します（ページのリロード後） |
signOut() | サーバー側のセッションを失効させ、保存済みセッションを破棄します |
エラーは AcomoAuthError の code で判定します（invalid_argument / invalid_credentials / session_expired / no_session / network_error / unexpected_response）。
sessionStorage はタブ単位でセッションを保持します。localStorage で複数タブに共有する場合、ファサードは Web Locks API で更新を直列化するため、対応ブラウザを使用してください。複数の認証テナントを扱う場合は createWebAuthStorage(storage, 'キー名') で保存先を分けてください。
1 つのセッションを複数のクライアントで共有しない
セッションのトークンは更新のたびに新しい値へ入れ替わります。同じセッションを複数のアプリ・端末で使い回すと不正利用と判定され、セッション全体が失効します。用途ごとにサインインしてください。
Google などのソーシャルサインイン、パスワードの初期設定・リセット、メールアドレス確認は acomo の標準画面を使います。ユーザー操作のないサーバー処理にはアクセストークンを使ってください。
curl の最小リクエスト例
プレースホルダーを実環境の値に置き換えてください。秘密情報はリポジトリにコミットしないでください。
bash
curl -sS \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "x-tenant-id: YOUR_AUTH_TENANT_ID" \
"https://YOUR_ACOMO_HOST/api/v1/models"listWorkflowModels（GET /models）はモデル一覧を返します。開発者権限と Model:read に相当する権限が必要です。
TypeScript の最小リクエスト例
@acomo/client を利用する場合も、実行時に同じ Bearer とテナントコンテキストが必要です。クライアント生成時のベース URL と認証フックは組織の SDK 利用規約に従ってください。
typescript
const response = await fetch(`${baseUrl}/api/v1/models`, {
headers: {
Authorization: `Bearer ${accessToken}`,
'x-tenant-id': authTenantId,
},
})
if (response.status === 401) {
// トークン失効・テナント不一致を疑う
}
if (response.status === 403) {
// スコープまたはロール不足を疑う
}失敗時の見方
- 401 — トークン未設定・期限切れ・
x-tenant-idとセッションのテナント不一致 - 403 — 認証は成功したが、システム実行ポリシーまたはモデルポリシーが不足
- CORSエラー（ブラウザのみ） — 接続元URL設定で呼び出し元オリジンが許可されているか
「API」画面の「システム実行ポリシー」列と、発行したアクセストークンのスコープを照合してください。
接続確認
- 検証環境でOpenAPIのAuthorizeに両方のスキームを設定し、参照系GETのTry it outが成功すること（本番での更新系APIは避ける。OpenAPI仕様書）
- アクセストークン利用時、失効・ローテーション手順が運用側で決まっていること