Skip to content

API認証 ​

API呼び出しに必要な認証ヘッダー、テナント指定、401と403エラーの確認方法を説明します。

対象読者 ​

開発者

前提 ​

  • 連携先テナントの テナントID(authTenantId)を管理者から入手していること
  • 利用する認証方式に応じて、ユーザーセッションまたはアクセストークンを用意していること

知っておくこと ​

acomo APIは Bearer認証 と テナントヘッダー の組み合わせが必須です。ブラウザのフロントエンドも同じヘッダーを付与してバックエンドを呼び出します。

ヘッダー例説明
AuthorizationBearer eyJhbG...acomoのサインインで取得したセッションJWT、または アクセストークン
x-tenant-idyour-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) {
  // スコープまたはロール不足を疑う
}

失敗時の見方 ​

  1. 401 は、トークンの未設定・期限切れ、または x-tenant-id とセッションのテナント不一致です。
  2. 403 は、認証には成功していますが、システム実行ポリシー、アクションポリシー、またはデータアクセスポリシーが不足しています。
  3. CORSエラー(ブラウザのみ) は、接続元URL設定で呼び出し元のオリジンが許可されていないときに起きます。

「API」画面の「システム実行ポリシー」列と、発行したアクセストークンのスコープを照合してください。

接続確認 ​

  • 検証環境でOpenAPIのAuthorizeに両方のスキームを設定し、参照系のGETをTry it outして成功すること。本番での更新系APIは避けてください。注意は OpenAPI仕様書 を参照してください。
  • アクセストークン利用時、失効・ローテーション手順が運用側で決まっていること

うまくいかないとき ​

次に読む ​

対応製品バージョン: acomo 1.0.0 / 画面・操作の最終確認日: 2026年8月26日