使用 REST API

本文档介绍如何使用 Identity Platform REST API 执行常见的用户操作，例如登录用户和使用令牌。

准备工作

要使用 REST API，您需要一个 Identity Platform API 密钥。要获取密钥，请执行以下操作：

  1. 前往 Google Cloud 控制台中的身份提供方页面。
    转到“身份提供商”页面

  2. 点击应用设置详情。

  3. 复制 apiKey 字段。

请注意，所有 API 调用都需要使用 HTTPS。

调用 API

用自定义令牌交换 ID 和刷新令牌

您可以向 signInWithCustomToken 端点发出 HTTP POST 请求，将自定义身份验证令牌换成 ID 和刷新令牌。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
token 字符串 从其中创建 ID 和刷新令牌对的 Identity Platform 自定义令牌。
returnSecureToken boolean 是否返回 ID 和刷新令牌。应始终为 true。
tenantId 字符串 用户登录的租户 ID。仅在多租户中使用。
必须与令牌中的 tenant_id 匹配。
自定义令牌声明
属性 名称 说明
alg 算法 应为 RS256。
iss 颁发者 您项目的服务账号电子邮件地址。
sub Subject 您项目的服务账号电子邮件地址。
aud 受众 https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit
iat 颁发时间 当前时间（与 UNIX 计时原点之间相隔的秒数）。
exp 到期时间 令牌到期的时间（与 UNIX 计时原点之间相隔的秒数），该时间可能比 iat 晚最多 3600 秒。
注意：这仅会控制自定义令牌本身的过期时间。但是，一旦您使用 signInWithCustomToken() 让用户登录，他们将一直在设备上保持登录状态，直到其会话失效或用户退出账号为止。
uid 用户 ID 用户的唯一标识符，长度介于 1-36 个字符之间。
tenant_id 租户 ID 用户登录的租户的标识符。
claims（可选） 要包含在安全规则 auth 或 request.auth 变量中的可选自定义声明。
响应载荷
属性名称 类型 说明
idToken 字符串 从提供的自定义令牌生成的 Identity Platform ID 令牌。
refreshToken 字符串 从提供的自定义令牌生成的 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"token":"[CUSTOM_TOKEN]","returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应包含与自定义令牌关联的 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "idToken": "[ID_TOKEN]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600"
}

常见错误代码

  • INVALID_CUSTOM_TOKEN：自定义令牌格式不正确或令牌因某种原因（如过期、签名无效等）无效
  • CREDENTIAL_MISMATCH：自定义令牌对应于其他 Google Cloud 项目。

用刷新令牌交换 ID 令牌

您可以通过向 securetoken.googleapis.com 端点发出 HTTP POST 请求来刷新 Identity Platform ID 令牌。

方法：POST

Content-Type: application/x-www-form-urlencoded

端点 
https://securetoken.googleapis.com/v1/token?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
grant_type 字符串 刷新令牌的授权类型，始终为“refresh_token”。
refresh_token 字符串 Identity Platform 刷新令牌。
响应载荷
属性名称 类型 说明
expires_in 字符串 ID 令牌到期前剩余的秒数。
token_type 字符串 刷新令牌的类型，始终为“Bearer”。
refresh_token 字符串 请求中提供的 Identity Platform 刷新令牌或新的刷新令牌。
id_token 字符串 Identity Platform ID 令牌。
user_id 字符串 与提供的 ID 令牌相对应的 uid。
project_id 字符串 您的 Google Cloud 项目 ID。

示例请求 

curl 'https://securetoken.googleapis.com/v1/token?key=[API_KEY]' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&refresh_token=[REFRESH_TOKEN]'

200 OK HTTP 状态代码表示请求成功。响应包含新的 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "expires_in": "3600",
  "token_type": "Bearer",
  "refresh_token": "[REFRESH_TOKEN]",
  "id_token": "[ID_TOKEN]",
  "user_id": "tRcfmLH7o2XrNELi...",
  "project_id": "1234567890"
}

常见错误代码

  • TOKEN_EXPIRED：用户凭据已失效。用户必须重新登录。
  • USER_DISABLED：用户账号已被管理员停用。
  • USER_NOT_FOUND：未找到与刷新令牌对应的用户。 该用户可能已被删除。
  • API 密钥无效。请传递有效的 API 密钥。（提供的 API 密钥无效）
  • INVALID_REFRESH_TOKEN：提供的刷新令牌无效。
  • 收到的 JSON 载荷无效。未知名称 \"refresh_tokens\"：无法绑定查询参数。在请求消息中找不到“refresh_tokens”字段。
  • INVALID_GRANT_TYPE：指定的授权类型无效。
  • MISSING_REFRESH_TOKEN：未提供刷新令牌。
  • PROJECT_NUMBER_MISMATCH：刷新令牌的项目编号与所提供的 API 密钥的项目编号不匹配。

通过电子邮件/密码注册

您可以向 Auth signupNewUser 端点发出 HTTP POST 请求，以创建新的电子邮件地址和密码用户。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
电子邮件 字符串 要创建的用户的电子邮件。
密码 字符串 要创建的用户的密码。
returnSecureToken boolean 是否返回 ID 和刷新令牌。应始终为 true。
tenantId 字符串 要创建的用户的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
idToken 字符串 新创建的用户的 Identity Platform ID 令牌。
电子邮件 字符串 新创建的用户的电子邮件。
refreshToken 字符串 新创建的用户的 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。
localId 字符串 新创建的用户的 uid。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"email":"[user@example.com]","password":"[PASSWORD]","returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应包含与新账号关联的 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "idToken": "[ID_TOKEN]",
  "email": "[user@example.com]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "localId": "tRcfmLH7..."
}

常见错误代码

  • EMAIL_EXISTS：该电子邮件地址已被其他账号使用。
  • OPERATION_NOT_ALLOWED：此项目已停用密码登录。
  • TOO_MANY_ATTEMPTS_TRY_LATER：由于异常活动，我们已阻止此设备的所有请求。请稍后重试。

通过电子邮件/密码登录

您可以向 Auth verifyPassword 端点发出 HTTP POST 请求，让用户使用电子邮件地址和密码登录。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
电子邮件 字符串 用户用于登录的电子邮件。
密码 字符串 账号的密码。
returnSecureToken boolean 是否返回 ID 和刷新令牌。应始终为 true。
tenantId 字符串 用户登录的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
idToken 字符串 经过身份验证的用户的 Identity Platform ID 令牌。
电子邮件 字符串 经过身份验证的用户的电子邮件。
refreshToken 字符串 经过身份验证的用户的 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。
localId 字符串 经过身份验证的用户的 uid。
registered boolean 是否是现有账号的电子邮件。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"email":"[user@example.com]","password":"[PASSWORD]","returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应包含与现有电子邮件/密码账号关联的 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "localId": "ZY1rJK0eYLg...",
  "email": "[user@example.com]",
  "displayName": "",
  "idToken": "[ID_TOKEN]",
  "registered": true,
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600"
}

常见错误代码

  • EMAIL_NOT_FOUND：没有与此标识符对应的用户记录。用户可能已被删除。
  • INVALID_PASSWORD：密码无效或用户没有密码。
  • USER_DISABLED：用户账号已被管理员停用。

匿名登录

您可以向 Auth signupNewUser 端点发出 HTTP POST 请求，让用户匿名登录。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
returnSecureToken boolean 是否返回 ID 和刷新令牌。应始终为 true。
tenantId 字符串 用户登录的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
idToken 字符串 新创建的用户的 Identity Platform ID 令牌。
电子邮件 字符串 由于用户是匿名的，此属性应为空。
refreshToken 字符串 新创建的用户的 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。
localId 字符串 新创建的用户的 uid。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与匿名用户关联的 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "idToken": "[ID_TOKEN]",
  "email": "",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "localId": "Jws4SVjpT..."
}

常见错误代码

  • OPERATION_NOT_ALLOWED：此项目已停用匿名用户登录。

通过 OAuth 凭据登录

您可以向 Auth verifyAssertion 端点发出 HTTP POST 请求，以便使用 OAuth 凭据让用户登录。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
requestUri 字符串 IDP 将用户重定向回此 URI。
postBody 字符串 包含 OAuth 凭据（ID 令牌或访问令牌）和颁发凭据的提供商 ID。
returnSecureToken boolean 是否返回 ID 和刷新令牌。应始终为 true。
returnIdpCredential boolean 出现以下错误时是否强制返回 OAuth 凭据：FEDERATED_USER_ID_ALREADY_LINKED 和 EMAIL_EXISTS。
tenantId 字符串 用户登录的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
federatedId 字符串 标识 IdP 账号的唯一 ID。
providerId 字符串 关联的提供商的 ID（例如 Google 提供商的 ID 为“google.com”）。
localId 字符串 经过身份验证的用户的 uid。
emailVerified boolean 登录电子邮件是否通过验证。
电子邮件 字符串 账号的电子邮件。
oauthIdToken 字符串 OIDC ID 令牌（如有）。
oauthAccessToken 字符串 OAuth 访问令牌（如有）。
oauthTokenSecret 字符串 OAuth 1.0 令牌密钥（如有）。
rawUserInfo 字符串 字符串化的 JSON 响应，包含与提供的 OAuth 凭据对应的所有 IdP 数据。
firstName 字符串 账号的名字。
lastName 字符串 账号的姓氏。
fullName 字符串 账号的完整名称。
displayName 字符串 账号的显示名。
photoUrl 字符串 账号的照片网址。
idToken 字符串 经过身份验证的用户的 Identity Platform ID 令牌。
refreshToken 字符串 经过身份验证的用户的 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。
needConfirmation boolean 是否已存在具有相同凭据的其他账号。用户需要登录原始账号，然后将当前凭据与其相关联。

包含 OAuth ID 令牌的示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"postBody":"id_token=[GOOGLE_ID_TOKEN]&providerId=[google.com]","requestUri":"[http://localhost]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与经过身份验证的用户关联的 Identity Platform ID 令牌和刷新令牌。

包含 OAuth ID 令牌的响应示例 

{
  "federatedId": "https://accounts.google.com/1234567890",
  "providerId": "google.com",
  "localId": "5xwsPCWYo...",
  "emailVerified": true,
  "email": "user@example.com",
  "oauthIdToken": "[GOOGLE_ID_TOKEN]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "displayName": "John Doe",
  "idToken": "[ID_TOKEN]",
  "photoUrl": "https://lh5.googleusercontent.com/.../photo.jpg",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "rawUserInfo": "{\"updated_time\":\"2017-02-22T01:10:57+0000\",\"gender\":\"male\", ...}"
}

包含 OAuth 访问令牌的示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"postBody":"access_token=[FACEBOOK_ACCESS_TOKEN]&providerId=[facebook.com]","requestUri":"[http://localhost]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与经过身份验证的用户关联的 Identity Platform ID 令牌和刷新令牌。

包含 OAuth 访问令牌的响应示例 

{
  "federatedId": "http://facebook.com/1234567890",
  "providerId": "facebook.com",
  "localId": "5xwsPCWYo...",
  "emailVerified": true,
  "email": "user@example.com",
  "oauthAccessToken": "[FACEBOOK_ACCESS_TOKEN]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "displayName": "John Doe",
  "idToken": "[ID_TOKEN]",
  "photoUrl": "https://scontent.xx.fbcdn.net/v/...",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "rawUserInfo": "{\"updated_time\":\"2017-02-22T01:10:57+0000\",\"gender\":\"male\", ...}"
}

包含 Twitter OAuth 1.0 凭据的示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"postBody":"access_token=[TWITTER_ACCESS_TOKEN]&oauth_token_secret=[TWITTER_TOKEN_SECRET]&providerId=[twitter.com]","requestUri":"[http://localhost]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与经过身份验证的用户关联的 Identity Platform ID 令牌和刷新令牌。

包含 Twitter OAuth 1.0 凭据的响应示例 

{
  "federatedId": "http://twitter.com/1234567890",
  "providerId": "twitter.com",
  "localId": "5xwsPCWYo...",
  "emailVerified": true,
  "email": "user@example.com",
  "oauthAccessToken": "[OAUTH_ACCESS_TOKEN]",
  "oauthTokenSecret": "[OAUTH_TOKEN_SECRET]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "displayName": "John Doe",
  "idToken": "[ID_TOKEN]",
  "photoUrl": "http://abs.twimg.com/sticky/...",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "rawUserInfo": "{\"updated_time\":\"2017-02-22T01:10:57+0000\",\"gender\":\"male\", ...}"
}

常见错误代码

  • OPERATION_NOT_ALLOWED：此项目已停用相应的提供商。
  • INVALID_IDP_RESPONSE：提供的身份验证凭据格式不正确或已过期。

获取与电子邮件关联的提供商

通过向 Auth createAuthUri 端点发出 HTTP POST 请求，您可以查找与指定电子邮件关联的所有提供方。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:createAuthUri?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
identifier 字符串 用户的电子邮件地址
continueUri 字符串 IDP 将用户重定向回此 URI。对于此用例，这只是当前网址。
tenantId 字符串 用户登录的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
allProviders 字符串列表 用户之前登录使用过的提供商的列表。
registered boolean 是否是现有账号的电子邮件

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:createAuthUri?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"identifier":"[user@example.com]","continueUri":"[http://localhost:8080/app]"}'

200 OK HTTP 状态代码表示请求成功。响应包含与该电子邮件关联的提供商列表。

示例响应 

{
  "allProviders": [
    "password",
    "google.com"
  ],
  "registered": true
}

常见错误代码

  • INVALID_EMAIL：电子邮件地址的格式有误。

发送密码重置电子邮件

您可以向 Auth getOobConfirmationCode 端点发出 HTTP POST 请求，以发送重设密码电子邮件。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:sendOobCode?key=[API_KEY]
可选标头
属性名称 说明
X-Firebase-Locale 与用户的语言区域对应的语言代码。传递此值后，系统会将发送给用户的密码重置电子邮件本地化。
请求正文载荷
属性名称 类型 说明
requestType 字符串 要返回的 OOB 代码的种类。对于密码重置，应为“PASSWORD_RESET”。
电子邮件 字符串 用户的电子邮件地址。
tenantId 字符串 请求重置密码的用户的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
电子邮件 字符串 用户的电子邮件地址。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:sendOobCode?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"requestType":"PASSWORD_RESET","email":"[user@example.com]"}'

成功的请求会显示 200 OK HTTP 状态代码。

示例响应 

{
 "email": "[user@example.com]"
}

常见错误代码

  • EMAIL_NOT_FOUND：没有与此标识符对应的用户记录。用户可能已被删除。

验证密码重置代码

您可以通过向 Auth resetPassword 端点发出 HTTP POST 请求来验证密码重置代码。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:resetPassword?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
oobCode 字符串 发送到用户的电子邮件的电子邮件操作代码，用于重置密码。
tenantId 字符串 请求重置密码的用户的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
电子邮件 字符串 用户的电子邮件地址。
requestType 字符串 电子邮件操作代码的类型。应为“PASSWORD_RESET”。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:resetPassword?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"oobCode":"[PASSWORD_RESET_CODE]"}'

成功的请求会显示 200 OK HTTP 状态代码。

示例响应 

{
  "email": "[user@example.com]",
  "requestType": "PASSWORD_RESET"
}

常见错误代码

  • OPERATION_NOT_ALLOWED：此项目已停用密码登录。
  • EXPIRED_OOB_CODE：操作代码已过期。
  • INVALID_OOB_CODE：操作代码无效。如果该代码格式有误、已过期或已被使用，就可能会发生这种情况。

确认密码重置

您可以向 Auth resetPassword 端点发出 HTTP POST 请求，以应用重设密码更改。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:resetPassword?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
oobCode 字符串 发送到用户的电子邮件的电子邮件操作代码，用于重置密码。
newPassword 字符串 用户的新密码。
tenantId 字符串 请求重置密码的用户的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
电子邮件 字符串 用户的电子邮件地址。
requestType 字符串 电子邮件操作代码的类型。应为“PASSWORD_RESET”。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:resetPassword?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"oobCode":"[PASSWORD_RESET_CODE]","newPassword":"[NEW_PASSWORD]"}'

成功的请求会显示 200 OK HTTP 状态代码。

示例响应 

{
  "email": "[user@example.com]",
  "requestType": "PASSWORD_RESET"
}

常见错误代码

  • OPERATION_NOT_ALLOWED：此项目已停用密码登录。
  • EXPIRED_OOB_CODE：操作代码已过期。
  • INVALID_OOB_CODE：操作代码无效。如果该代码格式有误、已过期或已被使用，就可能会发生这种情况。
  • USER_DISABLED：用户账号已被管理员停用。

更改电子邮件

您可以通过向 Auth setAccountInfo 端点发出 HTTP POST 请求来更改用户的电子邮件地址。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
可选标头
属性名称 说明
X-Firebase-Locale 与用户的语言区域对应的语言代码。传递此值后，系统会将发送给用户的撤销电子邮件更改本地化。
请求正文载荷
属性名称 类型 说明
idToken 字符串 用户的 Identity Platform ID 令牌。
电子邮件 字符串 用户的新电子邮件。
returnSecureToken boolean 是否返回 ID 和刷新令牌。
响应载荷
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 用户的电子邮件地址。
passwordHash 字符串 密码的哈希版本。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
idToken 字符串 用户的新的 Identity Platform ID 令牌。
refreshToken 字符串 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary \
'{"idToken":"[GCIP_ID_TOKEN]","email":"[user@example2.com]","returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与用户关联的新 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "localId": "tRcfmLH7o2...",
  "email": "[user@example2.com]",
  "passwordHash": "...",
  "providerUserInfo": [
    {
      "providerId": "password",
      "federatedId": "[user@example2.com]"
    }
  ],
  "idToken": "[NEW_ID_TOKEN]",
  "refreshToken": "[NEW_REFRESH_TOKEN]",
  "expiresIn": "3600"
}

常见错误代码

  • EMAIL_EXISTS：该电子邮件地址已被其他账号使用。
  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。

更改密码

您可以向 Auth setAccountInfo 端点发出 HTTP POST 请求，以更改用户的密码。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 用户的 Identity Platform ID 令牌。
密码 字符串 用户的新密码。
returnSecureToken boolean 是否返回 ID 和刷新令牌。
响应载荷
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 用户的电子邮件地址。
passwordHash 字符串 密码的哈希版本。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
idToken 字符串 用户的新的 Identity Platform ID 令牌。
refreshToken 字符串 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary \
'{"idToken":"[GCIP_ID_TOKEN]","password":"[NEW_PASSWORD]","returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与用户关联的新 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "localId": "tRcfmLH7o2...",
  "email": "[user@example.com]",
  "passwordHash": "...",
  "providerUserInfo": [
    {
      "providerId": "password",
      "federatedId": "[user@example.com]"
    }
  ],
  "idToken": "[NEW_ID_TOKEN]",
  "refreshToken": "[NEW_REFRESH_TOKEN]",
  "expiresIn": "3600"
}

常见错误代码

  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。
  • WEAK_PASSWORD：密码长度必须至少为 6 个字符。

更新配置文件

您可以通过向 Auth setAccountInfo 端点发出 HTTP POST 请求来更新用户的个人资料（显示名 / 照片网址）。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 用户的 Identity Platform ID 令牌。
displayName 字符串 用户的新显示名。
photoUrl 字符串 用户的新照片网址。
deleteAttribute 字符串列表 要删除的特性列表，“DISPLAY_NAME”或“PHOTO_URL”。这会使这些值无效。
returnSecureToken boolean 是否返回 ID 和刷新令牌。
响应载荷
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 用户的电子邮件地址。
displayName 字符串 用户的新显示名。
photoUrl 字符串 用户的新照片网址。
passwordHash 字符串 密码的哈希版本。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
idToken 字符串 用户的新的 Identity Platform ID 令牌。
refreshToken 字符串 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary \
'{"idToken":"[ID_TOKEN]","displayName":"[NAME]","photoUrl":"[URL]","returnSecureToken":true}'

成功的请求会显示 200 OK HTTP 状态代码。

示例响应 

{
  "localId": "tRcfmLH...",
  "email": "user@example2.com",
  "displayName": "John Doe",
  "photoUrl": "[http://localhost:8080/img1234567890/photo.png]",
  "passwordHash": "...",
  "providerUserInfo": [
    {
      "providerId": "password",
      "federatedId": "user@example2.com",
      "displayName": "John Doe",
      "photoUrl": "http://localhost:8080/img1234567890/photo.png"
    }
  ],
  "idToken": "[NEW_ID_TOKEN]",
  "refreshToken": "[NEW_REFRESH_TOKEN]",
  "expiresIn": "3600"
}

常见错误代码

  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。

获取用户数据

如需获取用户的数据，您可以向 Auth getAccountInfo 端点发出 HTTP POST 请求。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:lookup?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 账号的 Identity Platform ID 令牌。
响应载荷
属性名称 类型 说明
用户 JSON 对象列表 与给定 Identity Platform ID 令牌关联的账号。如需了解详情，请参阅下文。
响应载荷（users 数组内容）
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 账号的电子邮件。
emailVerified boolean 账号的电子邮件是否已经过验证。
displayName 字符串 账号的显示名。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
photoUrl 字符串 账号的照片网址。
passwordHash 字符串 密码的哈希版本。
passwordUpdatedAt double 账号密码上次更改的时间戳（以毫秒为单位）。
validSince 字符串 此时间戳（以秒为单位）标记一个边界，早于此边界的 Identity Platform ID 令牌被视为已撤消。
已停用 boolean 账号是否被停用。
lastLoginAt 字符串 账号上次登录的时间戳（以毫秒为单位）。
createdAt 字符串 创建账号的时间戳（以毫秒为单位）。
customAuth boolean 开发者是否对账号进行了身份验证。
tenantId 字符串 用户的租户 ID。仅在多租户环境中返回。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:lookup?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"idToken":"[GCIP_ID_TOKEN]"}'

200 OK HTTP 状态代码表示请求成功。响应中将包含与账号关联的所有用户信息。

示例响应 

{
  "users": [
    {
      "localId": "ZY1rJK0...",
      "email": "user@example.com",
      "emailVerified": false,
      "displayName": "John Doe",
      "providerUserInfo": [
        {
          "providerId": "password",
          "displayName": "John Doe",
          "photoUrl": "http://localhost:8080/img1234567890/photo.png",
          "federatedId": "user@example.com",
          "email": "user@example.com",
          "rawId": "user@example.com",
          "screenName": "user@example.com"
        }
      ],
      "photoUrl": "https://lh5.googleusercontent.com/.../photo.jpg",
      "passwordHash": "...",
      "passwordUpdatedAt": 1.484124177E12,
      "validSince": "1484124177",
      "disabled": false,
      "lastLoginAt": "1484628946000",
      "createdAt": "1484124142000",
      "customAuth": false
    }
  ]
}

常见错误代码

  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。
  • USER_NOT_FOUND：没有与此标识符对应的用户记录。用户可能已被删除。

您可以通过向 Auth setAccountInfo 端点发出 HTTP POST 请求，将电子邮件地址/密码与当前用户相关联。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 您尝试将凭据关联到的账号的 Identity Platform ID 令牌。
电子邮件 字符串 要与账号关联的电子邮件。
密码 字符串 账号的新密码。
returnSecureToken 字符串 是否返回 ID 和刷新令牌。应始终为 true。
响应载荷
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 账号的电子邮件。
displayName 字符串 账号的显示名。
photoUrl 字符串 账号的照片网址。
passwordHash 字符串 密码的哈希版本。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
emailVerified boolean 账号的电子邮件是否已经过验证。
idToken 字符串 用户的新的 Identity Platform ID 令牌。
refreshToken 字符串 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary \
'{"idToken":"[ID_TOKEN]","email":"[user@example.com]","password":"[PASS]","returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与经过身份验证的用户关联的 Identity Platform ID 令牌和刷新令牌。

示例响应 

{
  "localId": "huDwUz...",
  "email": "user@example.com",
  "displayName": "John Doe",
  "photoUrl": "https://lh5.googleusercontent.com/.../photo.jpg",
  "passwordHash": "...",
  "providerUserInfo": [
    {
      "providerId": "password",
      "federatedId": "user@example.com"
    }
  ],
  "idToken": "[ID_TOKEN]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "emailVerified": false
}

常见错误代码

  • CREDENTIAL_TOO_OLD_LOGIN_AGAIN：用户凭据已失效。用户必须重新登录。
  • TOKEN_EXPIRED：用户凭据已失效。用户必须重新登录。
  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。
  • WEAK_PASSWORD：密码长度必须至少为 6 个字符。

您可以通过向 Auth verifyAssertion 端点发出 HTTP POST 请求，将 OAuth 凭据与用户关联起来。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 您尝试将凭据关联到的账号的 Identity Platform ID 令牌。
requestUri 字符串 IDP 将用户重定向回此 URI。
postBody 字符串 包含 OAuth 凭据（ID 令牌或访问令牌）和颁发凭据的提供商 ID。
returnSecureToken boolean 是否返回 ID 和刷新令牌。应始终为 true。
returnIdpCredential boolean 出现以下错误时是否强制返回 OAuth 凭据：FEDERATED_USER_ID_ALREADY_LINKED 和 EMAIL_EXISTS。
响应载荷
属性名称 类型 说明
federatedId 字符串 标识 IdP 账号的唯一 ID。
providerId 字符串 关联的提供商的 ID（例如 Google 提供商的 ID 为“google.com”）。
localId 字符串 经过身份验证的用户的 uid。
emailVerified boolean 登录电子邮件是否通过验证。
电子邮件 字符串 账号的电子邮件。
oauthIdToken 字符串 OIDC ID 令牌（如有）。
oauthAccessToken 字符串 OAuth 访问令牌（如有）。
oauthTokenSecret 字符串 OAuth 1.0 令牌密钥（如有）。
rawUserInfo 字符串 字符串化的 JSON 响应，包含与提供的 OAuth 凭据对应的所有 IdP 数据。
firstName 字符串 账号的名字。
lastName 字符串 账号的姓氏。
fullName 字符串 账号的完整名称。
displayName 字符串 账号的显示名。
photoUrl 字符串 账号的照片网址。
idToken 字符串 经过身份验证的用户的 Identity Platform ID 令牌。
refreshToken 字符串 经过身份验证的用户的 Identity Platform 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。

包含 OAuth ID 令牌的示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"postBody":"id_token=[GOOGLE_ID_TOKEN]&providerId=[google.com]","requestUri":"[http://localhost]","idToken":"[GCIP_ID_TOKEN]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与经过身份验证的用户关联的 Identity Platform ID 令牌和刷新令牌。

包含 OAuth ID 令牌的响应示例 

{
  "federatedId": "https://accounts.google.com/1234567890",
  "providerId": "google.com",
  "localId": "5xwsPCWYo...",
  "emailVerified": true,
  "email": "user@example.com",
  "oauthIdToken": "[GOOGLE_ID_TOKEN]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "displayName": "John Doe",
  "idToken": "[ID_TOKEN]",
  "photoUrl": "https://lh5.googleusercontent.com/.../photo.jpg",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "rawUserInfo": "{\"updated_time\":\"2017-02-22T01:10:57+0000\",\"gender\":\"male\", ...}"
}

包含 OAuth 访问令牌的示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"postBody":"access_token=[FACEBOOK_ACCESS_TOKEN]&providerId=[facebook.com]","idToken":"[GCIP_ID_TOKEN]","requestUri":"[http://localhost]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与经过身份验证的用户关联的 Identity Platform ID 令牌和刷新令牌。

包含 OAuth 访问令牌的响应示例 

{
  "federatedId": "http://facebook.com/1234567890",
  "providerId": "facebook.com",
  "localId": "5xwsPCWYo...",
  "emailVerified": true,
  "email": "user@example.com",
  "oauthAccessToken": "[FACEBOOK_ACCESS_TOKEN]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "displayName": "John Doe",
  "idToken": "[ID_TOKEN]",
  "photoUrl": "https://scontent.xx.fbcdn.net/v/...",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "rawUserInfo": "{\"updated_time\":\"2017-02-22T01:10:57+0000\",\"gender\":\"male\", ...}"
}

包含 Twitter OAuth 1.0 凭据的示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"postBody":"access_token=[TWITTER_ACCESS_TOKEN]&oauth_token_secret=[TWITTER_TOKEN_SECRET]&providerId=[twitter.com]","requestUri":"[http://localhost]","idToken":"[GCIP_ID_TOKEN]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应中包含与经过身份验证的用户关联的 Identity Platform ID 令牌和刷新令牌。

包含 Twitter OAuth 1.0 凭据的响应示例 

{
  "federatedId": "http://twitter.com/1234567890",
  "providerId": "twitter.com",
  "localId": "5xwsPCWYo...",
  "emailVerified": true,
  "email": "user@example.com",
  "oauthAccessToken": "[OAUTH_ACCESS_TOKEN]",
  "oauthTokenSecret": "[OAUTH_TOKEN_SECRET]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "displayName": "John Doe",
  "idToken": "[ID_TOKEN]",
  "photoUrl": "http://abs.twimg.com/sticky/...",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "rawUserInfo": "{\"updated_time\":\"2017-02-22T01:10:57+0000\",\"gender\":\"male\", ...}"
}

常见错误代码

  • OPERATION_NOT_ALLOWED：此项目已停用相应的提供商。
  • INVALID_IDP_RESPONSE：提供的身份验证凭据格式不正确或已过期。
  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。
  • EMAIL_EXISTS：该电子邮件地址已被其他账号使用。
  • FEDERATED_USER_ID_ALREADY_LINKED：此凭据已与其他用户账号关联。

您可以向 Auth setAccountInfo 端点发出 HTTP POST 请求，从而解除提供方与当前用户之间的关联。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 账号的 Identity Platform ID 令牌。
deleteProvider 字符串列表 要取消关联的提供商 ID 列表，例如：“google.com”、“password”等。
响应载荷
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 账号的电子邮件。
displayName 字符串 账号的显示名。
photoUrl 字符串 账号的照片网址。
passwordHash 字符串 密码的哈希版本。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
emailVerified boolean 账号的电子邮件是否已经过验证。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"idToken":"[GCIP_ID_TOKEN]","deleteProvider":["[facebook.com]"]}'

成功的请求会显示 200 OK HTTP 状态代码。

示例响应 

{
  "localId": "huDwUz...",
  "email": "user@example.com",
  "displayName": "John Doe",
  "photoUrl": "https://lh5.googleusercontent.com/.../photo.jpg",
  "passwordHash": "...",
  "providerUserInfo": [
    {
      "providerId": "google.com",
      "federatedId": "1234567890",
      "displayName": "John Doe",
      "photoUrl": "https://lh5.googleusercontent.com/.../photo.jpg"
    },
    {
      "providerId": "password",
      "federatedId": "user@example.com"
    }
  ],
  "emailVerified": "true"
}

常见错误代码

  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。

发送电子邮件验证

您可以向 Auth getOobConfirmationCode 端点发出 HTTP POST 请求，从而为当前用户发送电子邮件验证。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:sendOobCode?key=[API_KEY]
可选标头
属性名称 说明
X-Firebase-Locale 与用户的语言区域对应的语言代码。传递此值后，系统会将发送给用户的电子邮件验证本地化。
请求正文载荷
属性名称 类型 说明
requestType 字符串 要发送的确认码的类型。应始终为“VERIFY_EMAIL”。
idToken 字符串 要验证的用户的 Identity Platform ID 令牌。
响应载荷
属性名称 类型 说明
电子邮件 字符串 账号的电子邮件。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:sendOobCode?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"requestType":"VERIFY_EMAIL","idToken":"[GCIP_ID_TOKEN]"}'

成功的请求会显示 200 OK HTTP 状态代码。

示例响应 

{
  "email": "user@example.com"
}

常见错误代码

  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。
  • USER_NOT_FOUND：没有与此标识符对应的用户记录。用户可能已被删除。

确认电子邮件验证

您可以向 Auth setAccountInfo 端点发出 HTTP POST 请求，以确认电子邮件验证码。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
oobCode 字符串 发送到用户电子邮件用于电子邮件验证的操作代码。
tenantId 字符串 要验证电子邮件的用户的租户 ID。仅在多租户中使用。
响应载荷
属性名称 类型 说明
电子邮件 字符串 账号的电子邮件。
displayName 字符串 账号的显示名。
photoUrl 字符串 账号的照片网址。
passwordHash 字符串 密码哈希。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
emailVerified boolean 账号的电子邮件是否已经过验证。

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"oobCode":"[VERIFICATION_CODE]"}'

成功的请求会显示 200 OK HTTP 状态代码。

示例响应 

{
  "localId": "FhyStE...",
  "email": "user@example.com",
  "passwordHash": "...",
  "providerUserInfo": [
    {
      "providerId": "password",
      "federatedId": "user@example.com"
    }
  ]
}

常见错误代码

  • EXPIRED_OOB_CODE：操作代码已过期。
  • INVALID_OOB_CODE：操作代码无效。如果该代码格式有误、已过期或已被使用，就可能会发生这种情况。
  • USER_DISABLED：用户账号已被管理员停用。
  • EMAIL_NOT_FOUND：没有与此标识符对应的用户记录。用户可能已被删除。

删除账号

如需删除当前用户，您可以向 Auth deleteAccount 端点发出 HTTP POST 请求。

方法：POST

Content-Type：application/json

端点 
https://identitytoolkit.googleapis.com/v1/accounts:delete?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 要删除的用户的 Identity Platform ID 令牌。
响应载荷
属性名称 类型 说明

示例请求 

curl 'https://identitytoolkit.googleapis.com/v1/accounts:delete?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"idToken":"[GCIP_ID_TOKEN]"}'

成功的请求会显示 200 OK HTTP 状态代码。

常见错误代码

  • INVALID_ID_TOKEN：用户凭据已失效。用户必须重新登录。
  • USER_NOT_FOUND：没有与此标识符对应的用户记录。用户可能已被删除。

处理错误

以下是 Identity Platform 返回的常见错误示例：

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalid",
        "message": "CREDENTIAL_TOO_OLD_LOGIN_AGAIN"
      }
    ],
    "code": 400,
    "message": "CREDENTIAL_TOO_OLD_LOGIN_AGAIN"
  }
}

从 message 字段中获取错误代码。