公開API
認証して呼び出す

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

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

認証フローの概要

公開APIのエンドポイント（後述のトークン交換エンドポイント/tokenを除く）へのリクエストにはAuthorization: Bearer <token>ヘッダーを付与します。利用できるトークンは以下の2系統です。

  • bm loginで取得したJWT: 公開APIがそのまま受け付けます。ブラウザでログインしたユーザーの権限で実行されます。
  • 外部OIDC IdPが発行したID Tokenを交換したアクセストークン: ID Tokenをそのまま指定しても受け付けられません。トークン交換エンドポイントPOST /public/v1/tokenでアクセストークンに交換してから利用します。サービスアカウントの権限で実行されます。

外部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信頼ポリシーで設定するIssuer / Audience / Bound Claimsの呼び出し元別の具体値は、後述の呼び出し元別のID Token取得方法で説明します。

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

外部OIDC IdPを利用する場合、まず呼び出し元の環境でID Tokenを取得します。取得したID Tokenは次節「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);

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,
  }),
);

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を取得します。コード管理のbm syncと異なり、公式のbm-actionは使いません。

- 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);

core.getIDToken()を呼ぶには、このステップを含むジョブにpermissions: id-token: writeの指定が必要です。取得したID Tokenは後続ステップからsteps.get-token.outputs.idTokenとして参照できます。

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をアクセストークンに交換する

取得したID Tokenは、トークン交換エンドポイントでベースマキナのアクセストークンに交換します。

POST https://platform.basemachina.com/public/v1/token

リクエストボディはContent-Type: application/jsonで以下を送信します。subject_tokenに取得したID Tokenを指定します。

curl -X POST \
  "https://platform.basemachina.com/public/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "'"$ID_TOKEN"'",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt"
  }'

交換に成功すると、アクセストークンと有効期間（秒）が返ります。

{
  "access_token": "<アクセストークン>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 300
}

access_tokenはAuthorization: Bearerにそのまま渡してください。トークンの内部形式は予告なく変更される場合がありますので、デコードして中身を使うことは推奨されません。

トークン交換エンドポイントのエラーレスポンス

トークン交換エンドポイント/tokenのエラーレスポンスは、他の公開APIエンドポイントとは異なる形式で返ります。

形式はRFC 8693 OAuth 2.0 Token Exchange (opens in a new tab) / RFC 6749 §5.2 (opens in a new tab)準拠です。Content-Typeはapplication/jsonです。

レスポンスボディはerrorとerror_descriptionの2フィールドのみです。Problem Details形式のtype / code / status / title / instanceは含まれません。

{
  "error": "invalid_grant",
  "error_description": "The subject_token is invalid, expired, or rejected by the trust policy."
}

error_descriptionはRFC 6749 §5.2の文字種制限（ASCII printable、"と\を除く）に従うため、英語の固定文言で返ります。ローカライズされたメッセージは返らない点にご注意ください。

HTTPステータスとerror値の対応は以下の通りです。

HTTPステータスerror発生条件
400invalid_requestリクエストボディがJSONとして解釈できない
400invalid_grantsubject_tokenが無効、期限切れ、または信頼ポリシーに合致しない
415invalid_requestContent-Typeがapplication/json以外
422invalid_requestgrant_type / subject_token_typeの不一致や不足など
500server_errorベースマキナ側で予期しないエラーが発生した
503temporarily_unavailableベースマキナ側の一時障害

503時はRetry-Afterヘッダーで再試行までの待機秒数を返します。クライアントはこのヘッダーに従って再試行してください。

その他公開APIエンドポイントのエラーレスポンスは引き続きRFC 9457 Problem Details (opens in a new tab)形式（Content-Type: application/problem+json）です。詳細はAPIリファレンスを参照してください。

呼び出し例（共通）

ID Tokenをアクセストークンに交換したあとは、認証方式に関わらず同じ形式で公開APIのエンドポイントを呼び出します。access_tokenをAuthorization: Bearerに指定します。POST時はContent-Typeを必ず指定してください。

# 1. ID Token をアクセストークンに交換する
ACCESS_TOKEN=$(curl -s -X POST \
  "https://platform.basemachina.com/public/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "'"$ID_TOKEN"'",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt"
  }' | jq -r .access_token)
 
# 2. アクセストークンで公開APIを呼び出す
curl -X POST \
  "https://platform.basemachina.com/public/v1/projects/csi2hcc0iaejrqgivkfg/environments/9m4e2mr0ui3e8a215n4g/actions/send_email/executions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "user_id": "usr_01H..."
    }
  }'

エンドポイントとリクエスト・レスポンス形式の詳細はAPIリファレンスをご参照ください。

トークンの寿命

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

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

ID Tokenはトークン交換のsubject_tokenとしてのみ使うため、交換が完了するまで有効であれば十分です。交換で得たアクセストークンにはexpires_inで示される有効期限があります。アクセストークンは期限が切れるまで複数のリクエストで使い回し、期限が切れたら再度トークン交換してください。期限切れのアクセストークンを使うと公開APIは401 unauthorizedを返します。

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

関連情報

  • 公開APIとは — 公開APIの概要・対応する操作・アクションの識別子の扱い
  • APIリファレンス — エンドポイント・パラメーター・レスポンス・エラーコードの詳細
  • サービスアカウント — サービスアカウントの作成とOIDC信頼ポリシー設定の詳細手順
  • bm login — ローカル端末でJWTを取得するコマンドの説明
公開APIとはAPIリファレンス