👌
TiDB Cloud : IAM API を使った API キー管理

2025/09/08に公開
TiDB Cloud は Web コンソールからの操作だけでなく、REST API を通じてコントロールプレーンを操作することができます。IAM (Identity and Access Management) API を利用すると、その操作に必要なAPI キーの作成・一覧・更新・削除といった管理操作をCLIベースで行うことができます。記事執筆時点（2025年9月）ではまだbetaとして提供されています。

https://docs.pingcap.com/tidbcloud/api/v1beta1/iam/
このIAM APIを用いることでRBAC（ロールベース認証）のAPI発行や削除を行ったり、APIの一覧を取得することが可能です。

 TiDB Cloud IAMで利用できるロール一覧組織ロール

org:owner : Organization Owner（組織全体のフル管理者）

org:member : Organization Viewer（組織ビューアー、閲覧のみ）

org:billing_admin : Organization Billing Manager（請求管理者）

org:billing_viewer : Organization Billing Viewer（請求閲覧者）

org:audit_admin : Organization Console Audit Manager（監査ログ管理者）
プロジェクトロール

project:owner : Project Owner（プロジェクト全体の管理者）

project:dev : Project Data Access Read-Write（データアクセス 読み書き）

project:readonly : Project Data Access Read-Only（データアクセス 読み取り専用）

project:ctl_plane_viewer : Project Viewer（クラスタなどコントロールプレーンの閲覧）
この機能を使って発行されたAPIでTiDB Cloudの操作を行える一覧はこちらにまとまっています。

https://docs.pingcap.com/tidbcloud/api/v1beta1/iam/

これについては別の機会に、別途記事で触れたいと思います。

 さっそくやってみる
 1.APIキーの発行APIキーを発行するAPIであるIAM APIを操作するためには、APIキーが必要になります。このため最初のAPIはコンソールから発行を行います。

コンソールの左ペイン一番下からOrganization Settingsをクリックします。



左ペインのAPI Keyを選択してBy Organizationのトグルをオンにして、Create API Keyをクリックします。





Organizationは複数のプロジェクトを保有することができます。特定プロジェクトに権限を持つAPIキーを発行する場合はトグルをBy Projectに変更します。

APIキーが作成されるとPublic KeyとPrivate Keyが発行されますので手元にメモしておきます。


 HTTP Digest 認証IAM APIはHTTP Digest認証が用いられます。先ほど発行されたPublic KeyとPrivate Keyはそれぞれユーザー名とパスワードに当たります。これを平文でサーバに送らずに、サーバ側から送ってきた文字列をさらに組み合わせてハッシュ値を生成して認証要求をサーバに送ります。

 2. Project IDの取得コンソール左ペインからProjectsをクリックして、Project IDをコピーします。

 3. APIキーのテストでは次にテストを行います。まずは以下のコマンドでPublic key,Private Key,Project IDを環境変数にセットします。
export TIDB_CLOUD_PUBLIC_KEY="02GPFF40"
export TIDB_CLOUD_PRIVATE_KEY="80e053ef-xxxx-4e03-9144-9148a49b265e"
export PROJECT_ID="1372813089454541795"
次にテスト用にProjectに存在しているClusterの一覧を取得するコマンドを実行します。
curl --digest \
  -u $TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY \
  "https://api.tidbcloud.com/api/v1beta/projects/$PROJECT_ID/clusters?page=1&page_size=50" \
  | jq
出力結果{
  "items": [
    {
      "id": "10388536437965674003",
      "project_id": "1372813089454541795",
      "name": "NewFR",
      "cluster_type": "DEVELOPER",
      "cloud_provider": "AWS",
      "region": "eu-central-1",
      "status": {
        "tidb_version": "v7.5.6",
        "cluster_status": "AVAILABLE",
        "connection_strings": {
          "standard": {
            "host": "gateway01.eu-central-1.prod.aws.tidbcloud.com",
            "port": 4000
          }
        }
      }
    },
    {
      "id": "10642251548441872535",
      "project_id": "1372813089454541795",
      "name": "Japan",
      "cluster_type": "DEVELOPER",
      "cloud_provider": "AWS",
      "region": "ap-northeast-1",
      "status": {
        "tidb_version": "v7.5.2",
        "cluster_status": "AVAILABLE",
        "connection_strings": {
          "standard": {
            "host": "gateway01.ap-northeast-1.prod.aws.tidbcloud.com",
            "port": 4000
          }
        }
      }
    },
    {
      "id": "10371646486371344778",
      "project_id": "1372813089454541795",
      "name": "Cluster0",
      "cluster_type": "DEVELOPER",
      "cloud_provider": "AWS",
      "region": "eu-central-1",
      "status": {
        "tidb_version": "v7.5.6",
        "cluster_status": "AVAILABLE",
        "connection_strings": {
          "standard": {
            "host": "gateway01.eu-central-1.prod.aws.tidbcloud.com",
            "port": 4000
          }
        }
      }
    }
  ],
  "total": 3
}

 4. IAM API を利用した APIキーの作成APIキーが無事認識され動作していることがわかりましたので、このAPIキーを使ってIAM APIを呼び出し、新たにAPIキーを発行します。
curl -X POST --digest \
  -u "$TIDB_CLOUD_PUBLIC_KEY:$TIDB_CLOUD_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  "https://iam.tidbapi.com/v1beta1/apikeys" \
  -d '{
    "displayName": "demo-api-key-org-member",
    "role": "org:member"
  }' | jq
以下の様なレスポンスが戻れば無事APIキーが発行されています。
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:--  0:00:01 --:--:--     0
100   260  100   184  100    76     80     33  0:00:02  0:00:02 --:--:--   113
{
  "name": "orgs/1372813089209216952/apiKeys/563414",
  "accessKey": "G2L95640",
  "secretKey": "54bac826-1a56-4838-a75f-8635a90f07df",
  "displayName": "demo-api-key-org-member",
  "role": "org:member"
}
このAPIキーはorg:memberとして閲覧のみ可能なAPIキーです。Organizationが複数のプロジェクトを保有している場合、すべてのプロジェクトに対する閲覧権限を保有します。

コンソール上でも以下の通り新しくAPIキーが発行されています。


 5. API キーの利用について発行されたAPIキーの利用についてはこちらのドキュメントにまとまっています。

https://docs.pingcap.com/tidbcloud/api/v1beta1/iam/

クラスターのプランでできることは異なります。例えばStarterではバックアップの手動取得は行えず自動取得のみであるため、同様にAPI経由でもバックアップ取得は行えません。Starterプランでは以下の操作が行えるとドキュメントに記載されています。

 Starter クラスタでできること（TiDB Cloud API）クラスタ管理
クラスタ一覧の取得
クラスタの新規作成
クラスタ詳細の取得
クラスタ削除
クラスタ設定の更新（名前、ラベル、スケーリング設定、監査ログ設定など）
利用可能リージョン一覧の取得

ブランチ管理
ブランチ一覧の取得
ブランチの作成
ブランチ詳細の取得
ブランチ削除
ブランチのリセット（親ブランチの状態に戻す）

データのエクスポート
エクスポートタスク一覧の取得
エクスポートタスク作成（例: Parquet / SQL 形式での出力）
エクスポートタスク詳細の取得
エクスポートタスク削除
エクスポートタスクキャンセル

データのインポート
インポートタスク一覧の取得
インポートタスク作成（例: S3 上のデータをクラスタに取り込む）
インポートタスク詳細の取得
インポートタスクキャンセル
こちらについてはまた機会があれば別の記事で触れることができればと思います。