了解如何使用和管理 Firebase 的 API 密钥

API 密钥是用于在与 Firebase 和 Google 服务交互时将请求路由到您的 Firebase 项目的唯一字符串。本页介绍了有关 API 密钥的基本信息，以及使用和管理 Firebase 应用的 API 密钥的最佳实践。

以下是关于 Firebase 的 API 密钥的最重要知识点：

• Firebase 相关 API 仅使用 API 密钥来标识 Firebase 项目或应用，不用于授权调用 API（某些其他 API 允许这样做）。Firebase 相关 API 的授权是通过 Google Cloud IAM 权限、Firebase Security Rules 或 Firebase App Check 单独处理的，而不是通过 API 密钥。因此，如果您仅将 Firebase API 密钥用于 Firebase 相关 API，则可以将其包含在代码中。
• 我们建议您查看限制和限额并对所有 API 密钥（甚至是 Firebase API 密钥）添加适当的限制和限额。具体而言，请将密钥限制为仅适用于您在应用中实际使用的 API，并根据需要限制配额。请注意，所有 Firebase 预配的 API 密钥默认会应用“API 限制”。
• 请仅将 Firebase 配置的 API 密钥用于 Firebase 相关 API。对于所有其他 API（例如 Places API for Maps 或 Google AI Gemini API），请使用单独的 API 密钥。
• 我们强烈建议您使用 Firebase Security Rules 保护您的 Realtime Database、Cloud Firestore 和 Cloud Storage 数据。请勿仅依赖 API 密钥限制。

有关 API 密钥和 Firebase 的常规信息

Firebase 的 API 密钥与典型的 API 密钥不同

与 API 密钥的典型用法不同，Firebase 服务的 API 密钥不能用来控制对后端资源的访问权限；此项控制只能通过 Firebase Security Rules（用于控制哪些最终用户可以访问资源）和 Firebase App Check（用于控制哪些应用可以访问资源）来实现。

通常，您需要严密保护 API 密钥（例如，使用保险柜服务或将密钥设置为环境变量）；而 Firebase 服务的 API 密钥则可以包含在代码中或签入的配置文件中。

尽管 Firebase 服务的 API 密钥可以安全地包含在代码中，但您应该检查限制并对其施加适当的限制。

使用 Firebase Security Rules 保护您的 Realtime Database、Cloud Firestore 和 Cloud Storage 数据。请勿仅依赖于限制和/或模糊化 API 密钥。

创建 API 密钥

一个 Firebase 项目可以有多个 API 密钥，但每个 API 密钥只能与一个 Firebase 项目关联。

当您执行以下操作时，Firebase 会自动为您的项目创建 API 密钥：

• 创建 Firebase 项目 > Browser key（自动创建）
• 创建 Firebase Apple 应用 > iOS key（自动创建）
• 创建 Firebase Android 应用 > Android key（自动创建）

重要提示：默认情况下，Firebase 自动创建的 API 密钥会自动限制为一系列 API，这些 API 要求客户端在调用时提供 API 密钥。请参阅常见问题解答 Firebase 服务的 API 密钥是否默认受限？

您还可以在 Google Cloud 控制台中创建自己的 API 密钥，例如用于开发或调试的 API 密钥。您可以在本页面稍后部分中详细了解何时推荐执行此操作。

查找 API 密钥

您可以在 Google Cloud 控制台内的 API 和服务 > 凭据面板中查看和管理所有项目的 API 密钥。

您还可以在以下位置找到自动匹配到 Firebase 应用的 API 密钥。默认情况下，项目在同一平台（Apple、Android 或 Web）上的所有 Firebase 应用都将使用同一个 API 密钥。

• Firebase Apple 应用 - 可在 Firebase 配置文件 GoogleService-Info.plist 的 API_KEY 字段中查找自动匹配的 API 密钥。

• Firebase Android 应用 - 可在 Firebase 配置文件 google-services.json 的 current_key 字段中查找自动匹配的 API 密钥。

• Firebase Web 应用 - 可在 Firebase 配置对象的 apiKey 字段中查找自动匹配的 API 密钥。

使用 API 密钥

API 密钥用于在与 Firebase/Google 服务交互时标识 Firebase 项目。具体而言，它们可以将 API 请求与您的项目关联，用于配额和结算目的。它们也有助于访问公开数据。

例如，您可以显式使用 API 密钥，只需将其值作为查询参数传入 REST API 调用即可。以下示例展示了如何向 Dynamic Links Link Shortener API 发出请求：

POST https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY

当您的应用调用需要移动/Web 客户端提供的 API 密钥的 Firebase API 时，会在 Firebase 配置文件/对象中自动查找项目的 API 密钥。不过，您也可以使用环境变量等其他机制为您的应用提供 API 密钥。

查看限制并对 API 密钥施加适当的限制（推荐）

虽然没有必要将 Firebase 服务的 API 密钥视为机密，但您应该查看并应用本部分中所述的限制。

对于生产应用使用的 API 密钥，请谨慎更改其限制或限额。您应该先在测试应用中对测试 API 密钥的限制加以测试，然后再更改生产 API 密钥的限制或限额。

注意：如果您为 Firebase 服务使用的 API 密钥具有“API 限制”，并且您收到 API_KEY_SERVICE_BLOCKED 或“Forbidden 403”错误，请确保该 API 密钥包含密钥“API 限制”许可名单中的所有必需 API。

查看系统自动添加到 Firebase API 密钥许可名单的 API

当 Firebase 在您的项目中创建 API 密钥时，我们会自动为该密钥添加“API 限制”。添加到此许可名单中的 API 是 Firebase 相关 API，这些 API 要求客户端在调用时提供 API 密钥。请注意，使用 Firebase 服务所需的大多数 API 实际上不需要列入 API 密钥的许可名单。

由于 Firebase 会为所有 Firebase 服务添加必要的 API，因此 API 密钥的许可名单可能包含您未使用的 API。您可以从许可名单中移除 API，但必须非常小心，不要移除 Firebase 和您使用的 Firebase 服务所需的 API（请参阅每个服务/产品需要在许可名单中的 Firebase 相关 API 列表）。否则，您在调用 Firebase 服务时会遇到错误。

注意：在 2024 年 5 月，Firebase 会自动对所有现有不受限制的 Firebase 配置的 API 密钥应用 API 限制。如需了解详情，请参阅常见问题解答 Firebase 服务的 API 密钥是否默认受限？

使用基于密码的 Authentication 时收紧配额

无论您使用哪种身份验证方案，都可以使用 Firebase Security Rules 保护您的 Realtime Database、Cloud Firestore 和 Cloud Storage 数据。

如果您使用了基于密码的 Firebase Authentication，而有人掌握了您的 API 密钥，那么只要您的 Firebase 项目的数据库或 Cloud Storage 数据受到 Firebase Security Rules 的保护，他们就无法访问任何此类数据。但是，他们可以使用您的 API 密钥访问 Firebase 的身份验证端点，并向您的项目发出身份验证请求。

为了降低有人滥用 API 密钥进行暴力破解的可能性，您可以收紧 identitytoolkit.googleapis.com 端点的默认配额，使其满足应用的正常流量预期即可。但请注意，如果您收紧了此配额，当遇到应用用户激增的情况时，可能会收到登录错误，直到您增加配额为止。您可以在 Google Cloud 控制台中更改项目的 API 配额。

为任何非 Firebase 服务使用单独的受限 API 密钥

虽然用于 Firebase 服务的 API 密钥一般不需要视为机密，但如果这类 API 密钥是用于其他 Google Cloud API 时，则应采取一些额外的预防措施。

如果您（在任何平台上）使用非 Firebase 服务/产品的 Google Cloud API，我们强烈建议您创建单独的受限 API 密钥以用于这些 API。如果 API 用于收费的 Google Cloud 服务，这一点尤其重要。

例如，如果您在 iOS 上使用 Firebase ML 和 Cloud Vision API，则应单独创建 API 密钥，以仅用于访问 Cloud Vision API。

通过为非 Firebase API 使用单独的受限 API 密钥，您可以在必要时轮替或更换密钥，以及为 API 密钥施加额外的限制，同时不影响您使用 Firebase 服务。

查看有关如何创建 API 专用密钥的说明

以下说明介绍如何为一个名为 Super Service API 的虚构 API 创建单独的受限 API 密钥。

第 1 步：配置现有 API 密钥以禁止访问 Super Service API

1. 打开 Google Cloud 控制台中的凭据页面。收到提示时，选择您的项目。

2. 针对列表中的每个现有 API 密钥，打开修改视图。

3. 在“API 限制”部分中，选择限制密钥，然后向列表中添加您希望此 API 密钥有权访问的所有 API。切勿包含您要为其创建单独 API 密钥的 API（在此示例中为 Super Service API）。

   在配置 API 密钥的 API 限制时，您应明确声明该密钥有权访问的 API。默认情况下，当“API 限制”部分选择了“不限制密钥”时，即表示一个 API 密钥可用于访问已为项目启用的所有 API。

现在，您现有的 API 密钥不会授予对 Super Service API 的访问权限，但对于您添加到每个密钥的“API 限制”列表中的任何 API，仍可继续使用该密钥进行访问。

重要提示：如果您日后启用任何其他 API，则必须将其添加到相应 API 密钥的“API 限制”列表中。

第 2 步：创建并使用用于访问 Super Service API 的新 API 密钥

1. 返回凭据页面。确保您的 Firebase 项目仍处于选中状态。

2. 点击创建凭据 > API 密钥。记下新的 API 密钥，然后点击限制密钥。

3. 在“API 限制”部分，选择限制密钥，然后仅将 Super Service API 添加到列表中。

   这个新的 API 密钥仅授予对 Super Service API 的访问权限。

4. 将您的应用和服务配置为使用新的 API 密钥。

使用特定于环境的 API 密钥（推荐）

如果您针对不同的环境（例如预演和生产）设置了不同的 Firebase 项目，每个应用实例都必须与其对应的 Firebase 项目进行交互，这非常重要。例如，您的预演应用实例绝不应与 Firebase 生产项目通信。这也意味着您的预演应用需要使用与 Firebase 预演项目关联的 API 密钥。

为了减少将代码更改从开发环境部署到预演环境再到生产环境时的问题，与其在代码本身中添加 API 密钥，不如将其设置为环境变量或将其包含在配置文件中。

请注意，如果您同时使用 Firebase Local Emulator Suite 和 Firebase ML 进行开发，则必须创建并使用仅用于调试的 API 密钥。如需了解如何创建此类密钥，请参阅 Firebase ML 文档。

常见问题解答和问题排查

常见问题解答

Firebase 服务的 API 密钥是否默认受限？

是的，默认情况下，Firebase 自动配置的所有 API 密钥（用于 Firebase 相关 API）都会自动应用“API 限制”。请参阅此许可名单中的 Firebase 相关 API 列表。

添加到此许可名单中的 API 是 Firebase 服务从客户端代码调用的 API，并且需要 API 密钥来标识您的 Firebase 项目或应用。请注意，使用 Firebase 服务所需的大多数 API 实际上不需要包含在 API 密钥的许可名单中。

由于 Firebase 会为所有 Firebase 服务添加必要的 API，因此 API 密钥的许可名单可能包含您未使用的 API。 您可以从许可名单中移除 API，但必须非常小心，不要移除 Firebase 和您使用的 Firebase 服务所需的 API（请参阅每个服务/产品需要在许可名单中的 Firebase 相关 API 列表）。否则，您在调用 Firebase 服务时会遇到错误。

重要提示：所有 Firebase 相关 API 都不会使用 API 密钥来授权调用 API。通过 API 调用传递的 API 密钥仅用于标识 Firebase 项目或应用。

您可以在 Google Cloud 控制台的 API 和服务 > 凭据面板中查看所有 API 密钥及其“API 限制”。

请注意以下关于 Firebase 如何应用这些“API 限制”的信息：

• 自 2024 年 5 月起，Firebase 自动预配的所有新 API 密钥都将自动限制为 Firebase 相关 API 的列表。

• 在 2024 年 5 月，Firebase 之前自动预配的所有现有和不受限制的 API 密钥都将限制为 Firebase 相关 API 列表，以及项目当前启用的所有 API。

• Firebase 之前自动配置的所有现有且已受限的 API 密钥均未发生变化。

• 任何未由 Firebase 自动预配的现有 API 密钥都不会发生变化。

重要提示：如果您（在任何平台上）使用非 Firebase 服务/产品的 Google Cloud API，我们强烈建议您创建单独的受限 API 密钥以用于这些 API。

如何确定我的 Firebase 应用所关联的 API 密钥？

您可以使用以下任一方法来确定您的 Firebase 应用所关联的 API 密钥：

Firebase 控制台

1. 转到 项目设置，然后向下滚动到您的应用卡片。

2. 选择相关应用。

3. 获取相关应用的 Firebase 配置文件/对象，然后查找其 API 密钥：

   • Apple：下载 GoogleService-Info.plist，然后找到 API_KEY 字段

   • Android：下载 google-services.json，找到相关应用的配置（查找其软件包名称），然后找到 current_key 字段

   • Web：选择“配置”选项，然后找到 apiKey 字段

Firebase CLI

1. 运行下面的命令来获取相关应用的 Firebase 配置文件/对象：

   firebase apps:sdkconfig PLATFORM FIREBASE_APP_ID

   • PLATFORM（任一项）：IOS | ANDROID | WEB
   • FIREBASE_APP_ID：Firebase 为您的 Firebase 应用分配的唯一标识符（请参阅查找您的应用 ID）

2. 在应用输出的 Firebase 配置中，找到其 API 密钥：

   • Apple：找到 API_KEY 字段

   • Android：找到相关应用的配置（查找其软件包名称），然后找到 current_key 字段

   • Web：找到 apiKey 字段

REST API

1. 调用相关应用的适用端点，然后将 apiKeyId 值传递给下一步，以获取 API 密钥的 apiKeyId (UID)。

   • Apple：调用 projects.iosApps.get
   • Android：调用 projects.androidApps.get
   • Web：调用 projects.webApps.get

2. 通过调用 projects.locations.keys.getKeyString 获取 API 密钥字符串。

   此 keyString 值可以在应用的配置工件中找到 (Apple | Android | Web)。

我可以在 Firebase 配置文件/对象中为同一个 Firebase 应用列出两个 API 密钥吗？

• Firebase Apple 应用 - 每个应用都有自己的配置文件，并且只列出一个 API 密钥。

• Firebase Android 应用 - Firebase 项目中的所有 Android 应用都列在同一个配置文件中，并且每个应用只能列出一个 API 密钥。不过，这个配置文件中的每个应用都可以列出不同的密钥。

• Firebase Web 应用 - 每个应用都有自己的配置对象，并且只列出一个 API 密钥。

不过，您可以对一个应用使用多个 API 密钥。您必须提供一种供应用访问其他这些 API 密钥的机制，例如通过环境变量。用于访问其他 API 密钥的机制不能依赖于 Firebase 配置文件/对象中列出的这些 API 密钥。

Firebase 如何知道哪个 API 密钥要匹配到一个应用（比如在 Firebase 配置文件/对象中）？

在您首次获取应用的 Firebase 配置文件/对象时，Firebase 会检查您的项目中是否有任何施加了与应用相匹配的“应用限制”（如 Apple 应用的匹配软件包 ID）的现有 API 密钥。

如果 Firebase 没有找到任何匹配的受限密钥，那么它将在配置文件/对象中列出 iOS key（对于 Apple 应用）、Android key（对于 Android 应用）以及 Browser key（对于 Web 应用）（假设这些密钥存在，并且没有施加阻止它们与该应用匹配的“应用限制”）。

我可以手动删除 Firebase 配置文件/对象中的 API 密钥和字段吗？

您可以手动删除配置文件/对象中的 API 密钥。不过，您必须提供其他一些供您的应用访问 API 密钥的机制（例如通过环境变量）。否则，对 Firebase 服务的任何调用都将失败。

我可以使用其他 API 密钥手动修改我的 Firebase 配置文件/对象吗？

可以，您可以手动修改配置文件/对象，以便将其他 API 密钥与应用相关联。

可以手动修改 Firebase 配置文件/对象中的 API 密钥，但通常不建议这样做。这增加了访问 Firebase 服务时出现问题的可能性。但是，如果您选择修改配置文件/对象，请执行以下操作：

• 确保 API 密钥的范围限定为配置文件/对象中列出的项目 ID。
• 确保没有任何“API 密钥限制”会禁止将 API 密钥用于该应用。
• 确保已为 API 密钥应用适当的“API 限制”。请参阅 Firebase 相关 API 列表，了解每个 Firebase 服务/产品需要列入许可名单的 API。

请注意，如果您从控制台重新获取了应用的配置文件/对象，它将始终列出 Firebase 自动匹配到该应用的 API 密钥。因此，您需要酌情重复执行手动修改。

我可以将 API 密钥从一个 Firebase 项目移至另一个 Firebase 项目吗？

不可以，API 密钥仅标识某个特定的项目，无法移至其他项目。

如果我删除 Google Cloud 控制台中列出的 API 密钥，会发生什么？

如果您删除应用正在使用的 API 密钥，该应用发出的 API 调用将失败。您可能会收到表明您正在尝试使用无效 API 密钥的报告、电子邮件或错误。

删除 API 密钥是永久性操作，无法撤消。

Firebase API 密钥的“API 限制”许可名单中需要哪些 API？

对于 Firebase API 密钥，需要在密钥的“API 限制”许可名单中的唯一 API 是要求客户端在调用时提供 API 密钥的 API。请注意，很少有 Firebase 相关 API 具有此要求。您项目中启用的大多数 Firebase 相关 API 都不需要列入密钥的“API 限制”许可名单。

重要提示：所有 Firebase 相关 API 都不会使用 API 密钥来授权调用 API。通过 API 调用传递的 API 密钥仅用于标识 Firebase 项目或应用。

请使用下表确定哪些 Firebase 相关 API 需要添加到 Firebase API 密钥的“API 限制”许可名单中。请注意，Firebase API 密钥只能用于 Firebase 服务。详细了解如何针对特定类型的 API 使用单独的受限 API 密钥。

您可以在 Google Cloud 控制台内的 API 和服务 > 凭据面板中查看和管理项目的 API 密钥。

注意：如果您在尝试调用 Firebase 相关 API 时收到 API_KEY_SERVICE_BLOCKED 或“Forbidden 403”错误，并且您使用的 API 密钥包含此表格中列出的所有必需 API，请与 Firebase 支持团队联系。

API 名称（服务名称）	API 显示名称	关联的 Firebase 服务/产品
firebase.googleapis.com	Firebase Management API	所有产品
logging.googleapis.com	Cloud Logging API	所有产品
firebaseinstallations.googleapis.com	Firebase Installations API	Cloud Messaging、Crashlytics、In-App Messaging、Performance Monitoring、Remote Config、Firebase ML
firebaseappcheck.googleapis.com	Firebase App Check API	App Check
firebaseappdistribution.googleapis.com	Firebase App Distribution API	App Distribution
firebaseapptesters.googleapis.com	Firebase App Testers API	App Distribution
identitytoolkit.googleapis.com	Identity Toolkit API	Authentication
securetoken.googleapis.com	Token Service API	Authentication
firebaserules.googleapis.com *	Firebase Rules API	Cloud Firestore、Cloud Storage、Realtime Database
datastore.googleapis.com	Cloud Datastore API	Cloud Firestore
firestore.googleapis.com	Google Cloud Firestore API	Cloud Firestore
fcmregistrations.googleapis.com	FCM Registration API	Cloud Messaging
firebasestorage.googleapis.com	Cloud Storage for Firebase API	Cloud Storage
firebasedynamiclinks.googleapis.com	Firebase Dynamic Links API	Dynamic Links
firebasehosting.googleapis.com *	Firebase Hosting API	Hosting
firebaseinappmessaging.googleapis.com	Firebase In-App Messaging API	In-App Messaging
firebaseml.googleapis.com	Firebase ML API	Firebase ML
mlkit.googleapis.com **	ML Kit API	Firebase ML
mobilecrashreporting.googleapis.com	Mobile Crash Reporting API	Performance Monitoring
play.googleapis.com	Google Play Android Developer API	Performance Monitoring
firebaseremoteconfig.googleapis.com	Firebase Remote Config API	Performance Monitoring、Remote Config
firebaseremoteconfigrealtime.googleapis.com	Firebase Remote Config Realtime API	Performance Monitoring、Remote Config
cloudconfig.googleapis.com **	不适用	Remote Config
firebasedatabase.googleapis.com *	Firebase Realtime Database API	Realtime Database
firebasevertexai.googleapis.com	Vertex AI in Firebase API	Vertex AI in Firebase

^{* 仅当您将 Firebase API 密钥与第三方工具结合使用或直接通过 REST 访问 Firebase 服务/产品时，才需要此权限。}

^{** 适用于该产品的早期版本 SDK。如果您使用的是最新版 SDK，则该 API 无需列入密钥的许可名单。}

问题排查

如何修正显示“对此 API 的请求已被屏蔽”的 API_KEY_SERVICE_BLOCKED 或“Forbidden 403”错误？

如果您遇到 API_KEY_SERVICE_BLOCKED 错误或类似以下内容的错误，请按照此常见问题解答中的指南操作：

Forbidden: 403 POST https://example-service.googleapis.com/method: Requests to this API example-service.googleapis.com method google.example-service.rest.method are blocked.

您的应用用来调用该 API 的 API 密钥可能施加了“API 限制”，并且该密钥的许可名单中不包含该 API。

• 如果您在尝试使用 Firebase 相关服务/产品时收到此错误，请确保您使用的 API 密钥包含密钥“API 限制”许可名单中的所有必需 API。

• 如果您在尝试使用非 Firebase 服务时收到此错误，我们强烈建议您专门为该服务和 API 创建新的 API 密钥。Firebase API 密钥应仅用于 Firebase 服务/产品。详细了解如何针对特定类型的 API 使用单独的受限 API 密钥。

如何修复下面的错误：“无法从服务器获取这个 Firebase 应用的衡量 ID。”？

您的 Web 应用所用的 API 密钥可能施加了“API 限制”。如果是这种情况，请确保 Firebase Management API 位于允许的 API 列表中。

我收到了表明我的 API 密钥无效的电子邮件或错误。发生了什么情况？如何解决此问题？

以下是导致 API 密钥无效的几个最常见的原因：

• 该 API 密钥施加了“API 密钥限制”，这使其无法匹配到尝试使用该密钥的应用（以下简称“应用限制”）或无法用于被调用的 API（以下简称“API 限制”）。

• 该 API 密钥已从 Google Cloud 控制台内的项目中删除。

• 该 API 密钥不是为应用的 Firebase 配置文件/对象中列出的项目 ID 创建的。

解决此问题的一种方法是，获取应用的 Firebase 配置文件/对象的更新版本，然后用更新后的配置文件/对象替换掉旧的文件/对象。在发送配置文件以供下载或在控制台中显示配置对象之前，Firebase 会检查所列出的 API 密钥是否与应用匹配。