公開APIとは
公開APIは、ベースマキナのリソースを外部システムから操作するためのREST APIです。環境の一覧取得や、アクションの一覧取得・詳細取得・実行を、HTTPリクエストで実行できます。
主なユースケースは以下の通りです。
- 外部システムからベースマキナのアクションを実行する
- CI/CDのジョブからアクションを呼び出して定型作業を自動化する
- 自社のスクリプトやツールに、ベースマキナのアクションを組み込む
- AIエージェント(Claude Codeなど)からアクションをツールとして実行する
対応する操作
公開APIで提供している操作は次のとおりです。
- 環境: 一覧取得。有効化されている環境のみを返します
- アクション: 一覧取得・詳細取得・実行
- レビュー依頼: 作成・状態取得・承認後の実行。レビューが必須のアクションが対象です
- プロジェクトユーザー: 一覧取得・詳細取得と、プロジェクトへの追加・削除
- グループ: 一覧取得・詳細取得と、ユーザーの所属の追加・解除
グループ所属の付け外しを使うと、普段は誰も強い管理権限を持たず、承認が下りたときだけ付与する構成を組めます。作り方は必要なときだけ管理権限を付与するを参照してください。
アクションやデータソースなどの設定変更(作成・編集・削除)は提供していません。設定の作成・編集・削除にはベースマキナの管理画面、またはコード管理を使用してください。
ベースURL・各エンドポイントの詳細(リクエスト・レスポンス・パラメーター・エラーコードなど)はAPIリファレンスを参照してください。
アクションの識別子
公開APIではアクションをアクションID、または識別子で参照します。管理画面やコード管理で識別子を設定している場合は識別子を、未設定の場合は自動生成されたアクションIDを使います。アクション一覧・詳細のレスポンスに含まれるidを、そのまま実行時のaction_idに指定してください。
アクションの実行権限
公開APIでのアクション実行は、認証に使ったトークンの主体が持つ権限で実行されます。主体は認証方式によって決まります。
アクションに実行権限が設定されている場合、実行権限を持たない主体は403 forbiddenになります。サービスアカウントで実行する場合は、所属グループに対象アクションの実行権限を付与してください。環境ごとに実行権限を設定しているアクションでは、実行する環境で実行権限を制限している場合に、その環境の実行権限を所属グループに付与してください。実行権限は所属グループ単位で決まります。サービスアカウントごとに個別の権限は付与できません。
レビュー設定でレビューが必須のアクションは、公開APIから直接実行できず403 forbiddenを返します。この場合はレビュー依頼を作成し、承認後に実行してください。
レビュー依頼は、bm loginで取得したJWT(ログインしたユーザー)でも、サービスアカウントのアクセストークンでも作成できます。サービスアカウントで作成した場合、依頼者はそのサービスアカウントとして記録されます。承認はこれまでと同じく、レビュー設定で承認者に指定された人間のユーザーが行います。
承認されたレビュー依頼は、依頼者のサービスアカウントが公開APIの「承認済みレビュー依頼の実行」から実行できます。レビュー設定で「承認者もアクションを実行可能にする」が有効な場合は、承認者もユーザーとして実行できます。承認後の自動実行は、ユーザーが依頼した場合と同じ扱いです。ただし、次の場合は自動実行されず、statusがapprovedのまま残ります。
- 依頼の作成後に、実行する環境で利用制限が有効になった
- 依頼者のサービスアカウントが無効化・削除された
- 依頼者のサービスアカウントがプロジェクトから外れた
サービスアカウントが作成したレビュー依頼では、承認・却下したときの依頼者へのメール・Slack DMによる通知と、承認待ちのまま期限が近づいたレビュー依頼のリマインドDM、承認済みで未実行のレビュー依頼のリマインドDMは送信されません。サービスアカウント側では、公開APIのレビュー依頼の状態取得でstatusを確認してください。
レビュー依頼の有効期限(expiration)は任意です。省略した場合は7日後になります。
レビュー依頼の重複作成を防ぐ
レビュー依頼の作成時にIdempotency-Keyヘッダーで任意のキー(1〜255文字の表示可能なASCII文字、スペースは除く)を送ると、タイムアウト後の再送や同時リクエストでレビュー依頼が重複しません。同じ依頼者(ユーザーまたはサービスアカウント)が同じキーで送ったリクエストは、2回目以降は新しく作成されず、409 duplicate_requestと先に作成されたレビュー依頼のreview_request_idが返ります。ヘッダーを送らない場合は、リクエストのたびに新しいレビュー依頼が作成されます。
キーの有効範囲は依頼者ごとで、別の依頼者が同じキーを使っても重複とは見なされません。申請ごとに一意なキーを使ってください。内容(引数や説明など)の異なるリクエストで同じキーを使い回さないでください。キーに有効期限はなく、一度使ったキーは以後ずっと重複として扱われます。
レビュー依頼の状態取得では、依頼者自身が取り下げたレビュー依頼の status は rejected ではなく withdrawn になります。レビュー済みのユーザーごとの結果は reviews で取得できます。
公開APIから実行できないアクション
次のアクションはアクション実行画面からは実行できますが、公開APIからは実行できず422 argument_invalidを返します。
| 種別 |
|---|
| ファイルパラメーターを持つアクション |
| (旧)JavaScriptアクション |
| ストレージ(Amazon S3 / Google Cloud Storage)のダウンロード操作のアクション |
| 実行結果にファイル(バイナリデータ)が含まれるアクション |
公開APIはJSON形式で表現できる結果のみを返せます。HTTP APIアクションが画像やPDFなどのバイナリを返した場合や、JavaScriptアクションがファイルを返した場合は実行できません。公開APIでストレージのファイルを取得したい場合は、署名付きURL発行操作のアクションを使用してください。
また、次の状態のアクションは公開APIに限らず実行できず404 not_foundを返します。状態を解消してから実行してください。
| 状態 | 対処 |
|---|---|
| アクションが無効化されている | アクションを有効化する |
| データソースが現在の環境に接続されていない | データソースの接続先設定で現在の環境を有効にする |
認証
公開APIのエンドポイント(トークン交換エンドポイント/tokenを除く)はBearerトークン認証(Authorization: Bearer <token>)で保護されています。ローカル端末からはbm loginで取得したJWTを、CI/CDやクラウドからは外部OIDC IdPが発行したID Tokenをトークン交換エンドポイントでアクセストークンに交換して利用します。シナリオ別の取得手順と呼び出し例は認証して呼び出すを参照してください。
利用までの流れ
- ベースマキナの管理画面でサービスアカウントを用意し、CI/CDやクラウドから呼び出す場合はOIDC信頼ポリシーを設定する
- 認証して呼び出すを参考に、ローカルからは
bm loginで、CI/CDやクラウドからは外部OIDC ID Tokenをアクセストークンに交換して、呼び出し用のトークンを用意する - プロジェクトIDと環境IDを確認し、URLパスの
project_id・environment_idに指定する - APIリファレンスのエンドポイント定義に従って環境一覧・アクション一覧・詳細・実行を呼び出す
OpenAPI仕様
公開APIのインターフェースはOpenAPI仕様(YAML形式)として公開しています。仕様ファイルは次のURLから取得できます。
https://docs.basemachina.com/openapi/public_api.yaml
OpenAPI対応のツールへ仕様ファイルを取り込めば、APIクライアントの生成やリクエストの動作確認に活用できます。
エラーコード
エラーレスポンスはRFC 9457 Problem Details 形式(Content-Type: application/problem+json)で返ります。codeフィールドで分類されます。各コードの発生条件・レスポンス例はAPIリファレンスの各エンドポイントのレスポンス定義を参照してください。
トークン交換エンドポイント/tokenのエラーレスポンスのみ、RFC 8693 /
RFC 6749 §5.2 準拠の{ error, error_description }形式(Content-Type: application/json)で返ります。詳細は認証して呼び出すを参照してください。
unauthorized
401。Bearerトークンが欠落・期限切れ・検証失敗。
bad_request
400。URLパスやリクエストの文法レベルの不正。
forbidden
403。次のいずれかに当てはまる場合に返ります。
- 対象プロジェクト・アクションへの権限が足りない
- レビューが必須のアクションを直接実行した
- リモートMCP・CLIからのアクション実行の禁止を有効にした環境で、
bm loginのトークンを使ってアクションの実行、承認済みのレビュー依頼の実行、レビュー依頼の作成のいずれかをした
not_found
404。アクション・環境などのリソースが存在しない、または無効化されている。
method_not_allowed
405。許可されていないHTTPメソッドの利用。
state_conflict
409。アクションの状態不整合、またはプロジェクトのユーザー管理権限の持ち主がいなくなる所属の変更(プロジェクトからの削除、グループ所属の変更)。
duplicate_request
409。同じIdempotency-Keyで作成済みのレビュー依頼がある。既存のレビュー依頼のIDはreview_request_idに入ります。
payload_too_large
413。リクエストボディのサイズ超過。
unsupported_media_type
415。Content-Typeがapplication/json以外。
argument_invalid
422。引数・クエリパラメーターのバリデーション違反、または公開APIから実行できないアクションの呼び出し。
javascript_action_error
422。JavaScriptアクションのコードが投げた業務エラー。
data_source_error
422。データソースなど接続先のエラー。接続先のHTTPステータスを取得できた場合はdata_source.statusに格納される。
internal_error
500。ベースマキナ側で予期しないエラーが発生した。
service_unavailable
503。ベースマキナ側の一時障害。Retry-Afterヘッダーに従ってリトライ可能。