APIキーの管理 | 文書 - Roblox クリエーターハブ

Open Cloudは、APIキーを使用してAPIへのアクセスを認証および承認します。これにより、データストアや場所など、ゲーム内の特定のリソースにアクセスするための詳細な権限およびセキュリティ管理が可能になります。

すべてのOpen Cloud APIは、有効な権限を持つAPIキーを作成し、リクエストにx-api-keyヘッダーを含めることを必要とします。これにより、アプリケーションがあなたに代わってOpen Cloudに認証を行うことができます。

APIキーの作成

以下のテキスト中のAPIキーに関するすべての参照は、ユーザー所有のキーを指します。

リソースにアクセスするためのAPIキーを作成および構成できます。APIキーのアクセスは、その所有者であるユーザーの権限によって決まります。つまり、一般的に、そのユーザーが権限を持つリソース、個別のゲームや適切な役割を持つグループ所有のゲームにアクセスできます。一部のスコープは特定のゲームに制限されることがありますが、すべてではありません。

グループリソースを管理するためのAPIキーの作成方法の詳細については、以下のグループ所有リソースの管理のためのAPIキーの作成セクションをご覧ください。

APIキーを作成するには：

Creator Dashboardで、API Keysページに移動します。
Create API Keyボタンをクリックします。
APIキーのためにユニークな名前を入力します。たとえば、自分のゲームに場所を公開するためのPLACE_PUBLISHING_KEYのように、後で目的を思い出すための名前を使用してください。
Access Permissionsセクションで、Select API SystemメニューからAPIを選択します。必要に応じて、複数のAPIをキーに追加するためにこのステップを繰り返します。
必要に応じて、APIキーを使用してアクセスしたいゲームを選択します。

Restrict by Experienceを無効にすることもできます。これを無効にすると、APIキーはユーザー所有のすべてのゲームと、適切な権限を持つグループ所有のゲーム、将来作成するゲームにもアクセスできます。
Select Operationsドロップダウンから、APIキーで有効にしたい操作を選択します。

APIリファレンスのほとんどの操作には、必要な権限スコープが含まれています。たとえば、flush memory store操作には、universe.memory-store:flush権限が必要です。

すべてのスコープとそれをサポートするAPIのリストについては、Scopesをご覧ください。
(Optional) Securityセクションで、CIDR notationを使用してキーへのIPアクセスを明示的に制限します。ローカルマシンのIPアドレスを見つけて、そのIPアドレスや追加のIPアドレスをAccepted IP Addressesセクションに追加できます。固定IPがない場合、またはAPIキーをローカル環境でのみ使用する場合、Restrict IP addressesトグルをオフのままにしておくことができます。これにより、どのIPでもあなたのAPIキーを使用できるようになります。
(Optional) リソースに追加の保護を加えるために、キーの有効期限を設定します。
Save & Generate keyボタンをクリックします。
APIキーの文字列を安全な場所にコピーして保存します。公に利用可能なリポジトリには保存しないでください。
Creator DashboardのAPI ExtensionsページでAPIキーのステータスを確認します。

APIキーの文字列は、アプリケーションのパスワードに相当します。開発チーム以外の信頼できない個人と共有しないでください。

グループ所有リソースの管理のためのAPIキーの作成

APIキーは、ユーザーアカウントが持つすべてのリソースへのアクセス権を付与します。これは、グループ外の個人ゲームを含みます。個人アカウントのAPIキーをグループの自動化に使用し、そのキーが侵害されると、他のアクセス権を持つリソースもリスクにさらされる可能性があります。

これを防ぐために、別のAPIキーを専用の代替アカウントで作成することを強くお勧めします。アクセスは厳格に対象のグループに限定してください。この自動化専用の新しいアカウントには、対象グループへのアクセスのみを許可し、そのタスクに必要な最小限の権限を付与する必要があります。

自動化用の新しい専用のRobloxアカウントを作成します。
新しいアカウントをグループに招待します。
そのアカウントにタスクに必要な最小限の権限を持つグループの役割を割り当てます（例：「グループ体験を作成および編集のみ」）。
新しいアカウントにログインし、上記の手順に従ってAPIキーを作成します。
生成したAPIキーをグループリソース自動化に使用します。

APIキー管理のベストプラクティス

APIキーは敏感な資格情報であり、データへの不正アクセスを防ぐために安全に保管する必要があります。以下はAPIキー管理のためのベストプラクティスです。

アプリケーションごとに別々のキーを作成：各アプリケーションやユースケースに対して別々のAPIキーを作成し、アクセスを隔離し、キーが侵害された場合の影響を減少させます。
最低限の権限を選択：スコープを構成するときは、キーの意図された使用に対して必要最低限の権限を選択します。ゲームによってスコープのアクセスを制限できるスコープについては、必要な特定のゲームだけにアクセスを制限します。
IPアドレス制限を使用：特定のIPアドレスまたはCIDR範囲にAPIキーへのアクセスを制限し、知らない場所からの不正使用を防止します。ロブロックスのプレースでAPIキーを使用する際には、キーがロブロックスのサーバーで使用できるようにするため、IPアドレス制限を使用しないでください。
有効期限を設定：短期利用の場合は、有効期限を設定し、一定の期間後に自動的にキーを無効にすることで、キーが侵害された場合のリスクを減少させます。長期利用の場合は、有効期限を設定しないことをお勧めします。キーが期限切れになると、自動化が予期せず失敗する可能性があります。
グループリソース管理用に専用の代替アカウントを使用：グループリソース管理用には、グループ所有リソースの管理のためのAPIキーの作成セクションで詳述されているように、最小限の権限を持つ専用アカウントを使用します。
APIキーを安全に保管：ソースコード、バージョン管理システム、または公開される可能性のあるスクリプトに直接APIキーを保存しないでください。キーの保存とアクセスの管理には、シークレット管理システムを使用してください。ロブロックスのプレースでは、Secrets Storeを使用してください。
公開チャネルでAPIキーを共有しない：APIキーを公開コミュニケーションチャネル、フォーラム、ソーシャルメディアを通じて共有しないでください。安全でプライベートなチャネルを通じて信頼できるチームメンバーとだけ共有してください。キーが侵害された場合の影響を最小限に抑えるために、誰とキーを共有するかを制限します。

CIDR形式

リソースをさらに保護するために、API キーを作成する際に、通常のIPアドレスまたはCIDR notationを使用してAPIキーにアクセスできるIPアドレスを指定します。 CIDR IPアドレスは通常のIPアドレスと似ていますが、スラッシュとそれに続く小数点で、IPアドレスの重要なビット数を表します。

通常: 192.168.0.0
CIDR: 192.168.0.0/24

前者の部分はIPアドレスで、後者の部分はバイナリ形式で1のビット数をカウントするネットマスクです。前の例では、24は255.255.255.0（24個の1）を意味し、192.168.0.0から192.168.0.255までのすべてのIPを許可します。CIDR形式を理解することは、アプリケーションをサーバーで実行する計画がある場合に特に有用です。

APIキーのステータス

APIキーは最初はアクティブなステータスですが、その生涯の中で非アクティブになることがあります。APIキーのステータスが変更された理由や、APIキーをアクティブに戻す方法については、以下の表をご覧ください。

あなたまたはあなたのグループがAPIキーを60日間使用または更新しない場合、そのキーは自動的に期限切れになります。有効期限が設定されていなくてもそうなります。これは悪意のあるユーザーが古いAPIキーを使用するリスクを減少させます。もうAPIキーを使用しない場合は、手動で無効にするか削除すべきです。

ステータス	理由	解決策
アクティブ	問題なし。ユーザーはAPI呼び出しを認証するためにキーを使用できます。	N/A
無効	ユーザーがEnable Keyトグルを無効にしたため、キーが無効になりました。	Enable Keyトグルを有効にします。
期限切れ	キーの有効期限が切れました。	引き剥がすか、新しい有効期限を設定します。
自動期限切れ	ユーザーが過去60日間にキーを使用または更新していません。	Enable Keyトグルを無効にしてから有効にするか、キーの名前、説明、または有効期限など、キーのプロパティのいずれかを更新します。
取り消されました	グループキーのみ。キーを生成したアカウントが、グループのキーを管理するための十分なアクセス権限を持たなくなりました。	Regenerate Keyをクリックして、新しいシークレットを取得します。
監視中	ロブロックスの管理者がセキュリティ上の理由からキーのシークレットを変更しました。	Regenerate Keyをクリックして、新しいシークレットを取得します。
ユーザーによって監視中	キーを生成したアカウントがロブロックスによって監視されています。	そのアカウントの監視の問題を解決します。

APIキーのイントロスペクト

POST api-keys/v1/introspect

APIキーに関する情報を取得します。リクエスターのIPアドレスからキーが使用できるか、キーまたは最後に生成されたユーザーが監視されているかを確認します。

リクエスト

(application/json)

キー	値
apiKey	<api_key>

イントロスペクトAPIキーリクエストの例
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

レスポンス

各スコープオブジェクトに存在する可能性のあるリソース識別子は4つあります。

userId
groupId
universeId
universeDatastore

userIdおよびgroupId識別子は、クリエイターターゲットのスコープにのみ関連しています。universeDatastore識別子は、universe-datastoreターゲットのスコープにのみ関連しています。リソース識別子は、リソースの選択をサポートしないスコープには省略されます。

リソース識別子リストのアスタリスク（*）は、そのスコープがそのタイプのすべてのリソースに対する権限を持っていることを示します。

イントロスペクトAPIキーのレスポンスの例
{
  "name": "test key",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}