アプリを作る

認証

API キー、サービスアカウント、アクセストークン、利用者の id_token とのトークン交換、スコープとロールを説明します。

このページでは、アプリが Hane の公開 API を呼ぶときの資格情報と、利用者に代わって呼ぶためのトークン交換を説明します。どの資格情報も Authorization: Bearer で送ります。組織・プロジェクト・環境は URL に入れず、資格情報から決まります。

資格情報の種類

資格情報	形	期限	使いどころ
API キー	`hane_<env>_…`	発行のときに決める（付けなければ期限なし）	サービスアカウントとして呼ぶ。バッチ、CI、BFF のトークン交換
アクセストークン	トークン交換で Hane が発行する	15 分	利用者として呼ぶ。BFF、コンソール、hanectl
IdP の id_token	顧客の IdP が発行する	IdP による	トークン交換の入力と、組織に入る前の API（`GET /v1/auth/me` など）

サービスアカウントと API キー

サービスアカウントは、人でない呼出し元です。1 つのプロジェクトと環境に結び付き、作るときにスコープを決めます。スコープは後から変えられないので、足りなければ作り直します。

const sa = await unwrap(
  admin.POST("/v1/platform/service-accounts", {
    body: { name: "fleet-app", project: "fleet", environment: "dev", scopes: ["data:records.read", "agents:run"] },
  }),
);
const key = await unwrap(
  admin.POST("/v1/platform/service-accounts/{id}/keys", {
    params: { path: { id: sa.sa_id } },
    body: { expires_at: "2027-03-31T00:00:00Z" },
  }),
);
// key.secret はこの応答でしか返らない

API キーの発行と失効には platform:keys.manage が要ります。コンソールの「アクセス」→「サービスアカウントと API キー」でもできます。
失効は DELETE /v1/platform/service-accounts/{id}/keys/{keyId} で、次の要求から拒否されます。
発行の応答を受け取れなかった鍵は失効させ、発行し直してください。

トークン交換

POST /v1/auth/token は、IdP の id_token を、組織・プロジェクト・環境に結び付いたアクセストークンに交換します。OAuth 2.0 Token Exchange の形です。

利用者とアプリ（BFF）
利用者だけ

const t = await unwrap(
  anon.POST("/v1/auth/token", {
    body: {
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token: idToken,
      subject_token_type: "urn:ietf:params:oauth:token-type:id_token",
      actor_token: process.env.HANE_API_KEY!,
      actor_token_type: "urn:hane:params:token-type:api_key",
      organization: "acme",
      project: "fleet",
      environment: "dev",
    },
  }),
);
// t.access_token, t.expires_in, t.context.scopes

const t = await unwrap(
  anon.POST("/v1/auth/token", {
    body: {
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token: idToken,
      subject_token_type: "urn:ietf:params:oauth:token-type:id_token",
      organization: "acme",
      project: "fleet",
      environment: "dev",
    },
  }),
);

actor_token にアプリの API キーを渡すと、利用者が元の主体、アプリのサービスアカウントが実行主体になります。スコープは、利用者のスコープとアプリのスコープの共通部分です。
API キーは、交換先と同じ組織・プロジェクト・環境のものでなければ FORBIDDEN になります。API キーに期限があれば、アクセストークンはそれより後まで使えません。
利用者が組織のメンバーでなければ FORBIDDEN になります。project を渡したら environment も要ります。
応答の context には、組織、プロジェクト、環境、利用者の ID、ロール、グループ、スコープが入ります。画面の出し分けに使えます。

スコープ

スコープは <サービス>:<資源>.<操作> の形です。data:* のようにサービスごとにまとめて渡すこともできます。

サービス	主なスコープ
データ	`data:schemas.read`、`data:records.read`、`data:records.write`、`data:values.confirm`、`data:import`
定義	`definitions:read`、`definitions:apply`、`definitions:release`
Workflow	`workflows:read`、`workflows:operate`、`workflows:event-subscriptions.manage`
承認	`approvals:tasks.read`、`approvals:tasks.decide`
文書	`documents:read`、`documents:write`、`documents:download`、`documents:delete`
Agent	`agents:read`、`agents:run`
Communication	`communication:read`、`communication:contacts.write`
組織	`platform:read`、`platform:members.manage`、`platform:projects.manage`、`platform:keys.manage`
監査・使用量	`audit:read`、`usage:read`

参照アプリのサービスアカウントは、データの読み書きと値の確定、取り込み、Workflow の読み取り、Task の読み取りと決定、文書の読み書き、Agent の読み取りと実行を持っています。

ロール

組織のメンバーは、ロールでスコープを持ちます。

ロール	できること
owner	すべて
admin	すべてのスコープ
developer	読み取りに加えて、データの書込み、定義の apply と有効化、Agent の実行など
operator	読み取りに加えて、データの書込みと値の確定、Task の決定、文書の書込みなど
viewer	読み取りだけ

ロールはメンバーの招待のときに決めるほか、マニフェストの RoleBinding で人・グループ・サービスアカウントに足せます。ロール・グループ・API キーが変わると権限の世代が上がり、古い世代のトークンは拒否されます（POLICY_EPOCH_STALE）。そのときは交換し直してください。

次に読む

アプリの構成BFF でのトークン交換の置き場所

SDKtoken() でトークンを渡すクライアント

セキュリティHane のセキュリティの考え方