開発中の機能
公開API
認証して呼び出す

公開APIを認証して呼び出す

⚠️

この機能は現在開発中であり、まだ公開されていません。記載内容は今後変更される可能性があります。

公開APIはBearerトークン認証で保護されています。ローカル端末からの検証ではbm loginで取得したJWTを、自社バックエンドやCI/CDからの呼び出しでは外部OIDC IdPが発行したID Tokenをそれぞれ利用できます。本ページでは、シナリオ別に必要なトークンの取得方法と呼び出し例を示します。

認証フローの概要

公開APIへのリクエストにはAuthorization: Bearer <token>ヘッダーを付与します。利用できるトークンは以下の2系統です。

  • bm loginで取得したJWT: 公開APIがそのまま受け付けます。ブラウザでログインしたユーザーの権限で実行されます。
  • 外部OIDC IdPが発行したID Token: 公開APIはID Tokenを検証し、内部でサービスアカウントJWTに交換します。サービスアカウントの権限で実行されます。

外部OIDC ID Tokenを利用する場合、呼び出し元のシステムは特定のサービスに限定されません。OIDC IdPが/.well-known/openid-configurationを公開しており、ID Tokenが信頼ポリシーのIssuer / Audience / Bound Claimsを満たせば認証は成功します。

シナリオの選び方

シナリオ推奨トークン取得手段
ローカル端末からの検証・開発bm loginで取得したJWTbm login
GitHub ActionsなどのCI/CD外部OIDC ID TokenGitHub OIDC、GitLab OIDC など、各CIサービスのID Token発行機能
Google Cloud / AWS などのクラウドサービス上での実行外部OIDC ID Tokenメタデータサーバー、IAM Outbound Identity Federation など
自社IdP配下のサービス外部OIDC ID TokenAuth0 / Okta / Keycloak / Kubernetes など、自社で運用するOIDC IdP

ローカル端末から呼び出す（bm login）

ローカル端末から公開APIを呼び出して挙動を検証したい場合は、bm loginで取得したJWTをそのままAuthorization: Bearerに指定するのが最も簡単な方法です。

事前準備

  1. ローカル端末でbm loginを実行し、ブラウザでベースマキナにログインする
  2. ログイン成功後、認証情報が~/.basemachina/credentials.jsonに自動で保存される

credentials.jsonには以下の形式でJWTとメタ情報が保存されます。

{
  "token": "<JWT>",
  "email": "you@example.com",
  "expiresAt": 1735689600
}

呼び出し例

jqでcredentials.jsonからトークンを取り出し、環境変数に格納してからcurlで呼び出します。

export BM_TOKEN=$(jq -r .token ~/.basemachina/credentials.json)
 
curl -X POST \
  "https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions" \
  -H "Authorization: Bearer $BM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "user_id": "usr_01H..."
    }
  }'

jqが利用できないWindows環境では、PowerShellの(Get-Content ~/.basemachina/credentials.json | ConvertFrom-Json).tokenでも同等の値を取得できます。

トークンの期限切れ

credentials.jsonに保存されたJWTには有効期限があります。期限を過ぎたトークンを使うと公開APIは401 unauthorizedを返します。再度bm loginを実行すると、新しいJWTがcredentials.jsonに上書き保存されます。

OIDC利用時の前提条件

外部OIDC ID Tokenで公開APIを呼び出す場合、以下が完了している必要があります。

  • プロジェクトにサービスアカウントが作成・割り当て済みである
  • 呼び出し元のOIDC IdPに合わせて、サービスアカウントのOIDC信頼ポリシーが登録済みである

設定手順の詳細はOIDC信頼ポリシーの設定をご参照ください。

OIDC信頼ポリシーの設定はプロジェクト設定の「コード管理」セクションでのみ行なえます。コード管理機能を使わない場合も、同セクションから信頼ポリシーを設定してください。

呼び出し元別のID Token取得方法

Google Cloud（Cloud Run / GKE / GCE / Cloud Functions）

Google Cloud上のワークロードでは、google-auth-libraryを使い、ワークロードに紐づくサービスアカウントのID Tokenを取得します。メタデータサーバー経由で取得されるため、サービスアカウント鍵をアプリケーションに置く必要はありません。

import { GoogleAuth } from "google-auth-library";
 
const auth = new GoogleAuth();
const audience = "https://your-tenant.example.com";
const client = await auth.getIdTokenClient(audience);
const idToken = await client.idTokenProvider.fetchIdToken(audience);
 
const res = await fetch(
  "https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${idToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ arguments: { user_id: "usr_01H..." } }),
  },
);

OIDC信頼ポリシーは以下の項目で設定します。

項目設定値
Issuerhttps://accounts.google.com
Audienceクライアントが指定した値（例: https://your-tenant.example.com）
Bound Claims呼び出し元サービスアカウントを特定するclaim（例: key: email, pattern: my-app@my-project.iam.gserviceaccount.com）

AWS（EC2 / Lambda / ECS）

AWS上のワークロードでは、2025年11月に公開されたAWS IAM Outbound Identity Federation (opens in a new tab)を使い、sts:GetWebIdentityToken APIでID Tokenを取得します。AWSアカウントごとに固有のOIDC Issuer URLが自動生成され、/.well-known/openid-configurationと/.well-known/jwks.jsonが公開されます。

import { STSClient, GetWebIdentityTokenCommand } from "@aws-sdk/client-sts";
 
const sts = new STSClient({});
const audience = "https://your-tenant.example.com";
 
const { WebIdentityToken: idToken } = await sts.send(
  new GetWebIdentityTokenCommand({
    Audience: [audience],
    SigningAlgorithm: "ES384",
    DurationSeconds: 900,
  }),
);
 
const res = await fetch(
  "https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${idToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ arguments: { user_id: "usr_01H..." } }),
  },
);

EC2やLambdaに付与されているIAMロールには、sts:GetWebIdentityTokenの許可が必要です。

OIDC信頼ポリシーは以下の項目で設定します。

項目設定値
IssuerAWSアカウント固有のIssuer URL（例: https://<account-uuid>.tokens.sts.global.api.aws）。マネジメントコンソールから確認可能
Audienceクライアントが指定した値（例: https://your-tenant.example.com）
Bound Claims呼び出し元IAMロールを特定するclaim（例: key: aws:PrincipalArn, pattern: arn:aws:iam::123456789012:role/my-app-role）

AWS IAM Outbound Identity Federationは2025年11月19日以降、全AWS商用リージョン・GovCloud・China Regionsで追加コストなしで提供されています。

GitHub Actions

actions/github-scriptから@actions/coreのgetIDToken(audience)を呼んでID Tokenを取得し、curlで公開APIを呼び出します。コード管理のbm syncと異なり、公式のbm-actionは使いません。

name: Call BaseMachina Public API
on:
  workflow_dispatch:
 
permissions:
  id-token: write
  contents: read
 
jobs:
  call-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        id: get-token
        with:
          script: |
            const idToken = await core.getIDToken("https://your-tenant.example.com");
            core.setSecret(idToken);
            core.setOutput("idToken", idToken);
      - name: Execute action
        env:
          BM_TOKEN: ${{ steps.get-token.outputs.idToken }}
        run: |
          curl -X POST \
            "https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions" \
            -H "Authorization: Bearer $BM_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{ "arguments": { "user_id": "usr_01H..." } }'

OIDC信頼ポリシーは以下の項目で設定します。

項目設定値
Issuerhttps://token.actions.githubusercontent.com
Audiencecore.getIDToken()に渡した値（例: https://your-tenant.example.com）
Bound Claims呼び出し元リポジトリ・ブランチを特定するclaim（例: key: sub, pattern: repo:my-org/my-repo:ref:refs/heads/main）

その他のOIDC IdP（Auth0 / Okta / Kubernetes / 自社IdP など）

上記以外のOIDC IdPも、以下を満たせば利用できます。

  • /.well-known/openid-configurationでOIDC Discovery情報が公開されている
  • JWKSがHTTPSで公開されている
  • ID Tokenにiss、aud、信頼ポリシーで使うclaimが含まれている

ID Tokenの取得方法は各IdPのドキュメントに従ってください。KubernetesではaudienceパラメータをつけたProjected ServiceAccount Token（OIDC互換JWT）が利用できます。Auth0やOkta、Keycloakなど一般的なOIDC IdPでは、Authorization Code Flowや、各IdPの拡張機能でマシン間通信向けに発行したid_tokenが利用できます。

呼び出し例（共通）

ID Tokenを取得したあとは、認証方式に関わらず同じ形式でAPIを呼び出します。Authorizationに加えて、POST時はContent-Typeを必ず指定してください。

curl -X POST \
  "https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions" \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "user_id": "usr_01H..."
    }
  }'

エンドポイントとリクエスト・レスポンス形式の詳細は、アクションの一覧、アクションの詳細、アクションの実行をご参照ください。

トークンの寿命

外部OIDC ID Tokenの有効期限は発行元のOIDC IdPに依存します。代表的な値は以下の通りです。

発行元デフォルト有効期限
GitHub Actions5分
Google Cloud1時間
AWS IAM Outbound Identity Federationデフォルト1時間、最大3時間（DurationSecondsで指定）

公開APIは毎リクエストごとにトークンを検証して交換するため、リクエストごとに新しいID Tokenを取得することを推奨します。短命のID Tokenをキャッシュする場合は、有効期限を超えないよう注意してください。

bm loginで取得したJWTの有効期限切れ時の挙動は、「トークンの期限切れ」を参照してください。

関連情報

  • 公開APIとは — ベースURL・必須ヘッダー・エラーレスポンスの一覧
  • OIDC信頼ポリシーの設定 — サービスアカウント作成と信頼ポリシー設定の詳細手順
  • bm login — ローカル端末でJWTを取得するコマンドの説明
公開APIとはアクション一覧