テーマ
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と認証の設定は、組織の方針に従ってください。
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仕様書 を参照してください。
- アクセストークン利用時、失効・ローテーション手順が運用側で決まっていること