Firebase Auth REST API

API 用法

您可以通过 REST API 查询 Firebase Auth 后端。这可用于各种操作,例如 创建新用户、登录现有用户以及修改或删除这些用户。

在本文档中,API_KEY 是指 Web API 密钥。 可在 项目设置 页面。

<ph type="x-smartling-placeholder">

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

您可以通过向身份验证 verifyCustomToken 端点发出 HTTP POST 请求来将自定义身份验证令牌交换为 ID 和刷新令牌。

方法:POST

Content-Type:application/json

端点
https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
token 字符串 一个 Firebase Auth 自定义令牌,用以创建 ID 和刷新令牌对。
returnSecureToken 布尔值 是否返回 ID 和刷新令牌。应始终为 true。
响应载荷
属性名称 类型 说明
idToken 字符串 根据提供的自定义令牌生成的 Firebase Auth ID 令牌。
refreshToken 字符串 根据提供的自定义令牌生成的 Firebase Auth 刷新令牌。
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 状态代码表示请求成功。响应包含 Firebase ID 令牌和关联的刷新令牌 与自定义令牌相关联。

示例响应

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

常见错误代码

  • INVALID_CUSTOM_TOKEN:自定义令牌格式不正确或令牌因某种原因(如过期、签名无效等)无效
  • CREDENTIAL_MISMATCH:自定义令牌对应于其他 Firebase 项目。

用刷新令牌交换 ID 令牌

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

<ph type="x-smartling-placeholder">

方法:POST

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

端点
https://securetoken.googleapis.com/v1/token?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
grant_type 字符串 刷新令牌的授权类型,始终为“refresh_token”。
refresh_token 字符串 Firebase Authentication 刷新令牌。
响应载荷
属性名称 类型 说明
expires_in 字符串 ID 令牌到期前剩余的秒数。
token_type 字符串 刷新令牌的类型,始终为“Bearer”。
refresh_token 字符串 请求中提供的 Firebase Auth 刷新令牌或新的刷新令牌。
id_token 字符串 Firebase Auth ID 令牌。
user_id 字符串 与提供的 ID 令牌相对应的 uid。
project_id 字符串 您的 Firebase 项目 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 状态代码表示请求成功。响应中包含新的 Firebase 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 密钥的项目编号不匹配。

通过电子邮件/密码注册

您可以通过向身份验证 signupNewUser 端点发出 HTTP POST 请求创建新的电子邮件和密码用户。

方法:POST

Content-Type:application/json

端点
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
电子邮件 字符串 要创建的用户的电子邮件。
密码 字符串 要创建的用户的密码。
returnSecureToken 布尔值 是否返回 ID 和刷新令牌。应始终为 true。
响应载荷
属性名称 类型 说明
idToken 字符串 新创建的用户的 Firebase Auth ID 令牌。
电子邮件 字符串 新创建的用户的电子邮件。
refreshToken 字符串 新创建的用户的 Firebase Authentication 刷新令牌。
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 状态代码表示请求成功。响应包含 Firebase 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:由于异常活动,我们已阻止此设备的所有请求。请稍后重试。

通过电子邮件/密码登录

通过向身份验证 verifyPassword 端点发出 HTTP POST 请求,您可以让用户通过电子邮件和密码登录。

方法:POST

Content-Type:application/json

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

示例请求

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 状态代码表示请求成功。响应中包含 Firebase 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:用户账号已被管理员停用。

匿名登录

通过向身份验证 signupNewUser 端点发出 HTTP POST 请求,您可以让用户匿名登录。

方法:POST

Content-Type:application/json

端点
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
returnSecureToken 布尔值 是否返回 ID 和刷新令牌。应始终为 true。
响应载荷
属性名称 类型 说明
idToken 字符串 新创建的用户的 Firebase Auth ID 令牌。
电子邮件 字符串 由于用户是匿名的,此属性应为空。
refreshToken 字符串 新创建的用户的 Firebase Authentication 刷新令牌。
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 状态代码表示请求成功。响应中包含 Firebase ID 令牌和刷新令牌 与匿名用户共享内容

示例响应

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

常见错误代码

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

通过 OAuth 凭据登录

您可以通过向身份验证 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 布尔值 是否返回 ID 和刷新令牌。应始终为 true。
returnIdpCredential 布尔值 出现以下错误时是否强制返回 OAuth 凭据:FEDERATED_USER_ID_ALREADY_LINKED 和 EMAIL_EXISTS。
响应载荷
属性名称 类型 说明
federatedId 字符串 标识 IdP 账号的唯一 ID。
providerId 字符串 关联的提供商的 ID(例如 Google 提供商的 ID 为“google.com”)。
localId 字符串 经过身份验证的用户的 uid。
emailVerified 布尔值 登录电子邮件是否通过验证。
电子邮件 字符串 账号的电子邮件。
oauthIdToken 字符串 OIDC ID 令牌(如有)。
oauthAccessToken 字符串 OAuth 访问令牌(如有)。
oauthTokenSecret 字符串 OAuth 1.0 令牌密钥(如有)。
rawUserInfo 字符串 字符串化的 JSON 响应,包含与提供的 OAuth 凭据对应的所有 IdP 数据。
firstName 字符串 账号的名字。
lastName 字符串 账号的姓氏。
fullName 字符串 账号的完整名称。
displayName 字符串 账号的显示名。
photoUrl 字符串 账号的照片网址。
idToken 字符串 经过身份验证的用户的 Firebase Auth ID 令牌。
refreshToken 字符串 经过身份验证的用户的 Firebase Auth 刷新令牌。
expiresIn 字符串 ID 令牌到期前剩余的秒数。
needConfirmation 布尔值 是否已存在具有相同凭据的其他账号。用户需要登录原始账号,然后将当前凭据与其相关联。

使用 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 状态代码表示请求成功。响应包含 Firebase 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 状态代码表示请求成功。响应包含 Firebase 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 状态代码表示请求成功。响应包含 Firebase 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:提供的身份验证凭据格式不正确或已过期。

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

您可以通过向身份验证 createAuthUri 端点发出 HTTP POST 请求来查看与特定电子邮件关联的所有提供商。

方法:POST

Content-Type:application/json

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

示例请求

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:电子邮件地址的格式有误。

发送密码重置电子邮件

您可以通过向身份验证 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”。
电子邮件 字符串 用户的电子邮件地址。
响应载荷
属性名称 类型 说明
电子邮件 字符串 用户的电子邮件地址。

示例请求

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:没有与此标识符对应的用户记录。用户可能已被删除。

验证密码重置代码

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

方法:POST

Content-Type:application/json

端点
https://identitytoolkit.googleapis.com/v1/accounts:resetPassword?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
oobCode 字符串 发送到用户的电子邮件的电子邮件操作代码,用于重置密码。
响应载荷
属性名称 类型 说明
电子邮件 字符串 用户的电子邮件地址。
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:操作代码无效。如果该代码格式有误、已过期或已被使用,就可能会发生这种情况。

确认密码重置

您可以通过向身份验证 resetPassword 端点发出 HTTP POST 请求来应用密码重置更改。

方法:POST

Content-Type:application/json

端点
https://identitytoolkit.googleapis.com/v1/accounts:resetPassword?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
oobCode 字符串 发送到用户的电子邮件的电子邮件操作代码,用于重置密码。
newPassword 字符串 用户的新密码。
响应载荷
属性名称 类型 说明
电子邮件 字符串 用户的电子邮件地址。
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:用户账号已被管理员停用。

更改电子邮件

您可以通过向身份验证 setAccountInfo 端点发出 HTTP POST 请求来更改用户的电子邮件。

方法:POST

Content-Type:application/json

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

示例请求

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

200 OK HTTP 状态代码表示请求成功。响应包含新的 Firebase 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:用户凭据已失效。用户必须重新登录。

更改密码

您可以通过向身份验证 setAccountInfo 端点发出 HTTP POST 请求来更改用户的密码。

方法:POST

Content-Type:application/json

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

示例请求

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

200 OK HTTP 状态代码表示请求成功。响应包含新的 Firebase 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 个字符。

更新配置文件

您可以通过向身份验证 setAccountInfo 端点发出 HTTP POST 请求来更新用户的个人资料(显示名/照片网址)。

方法:POST

Content-Type:application/json

端点
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 用户的 Firebase Auth ID 令牌。
displayName 字符串 用户的新显示名。
photoUrl 字符串 用户的新照片网址。
deleteAttribute 字符串列表 要删除的特性列表,“DISPLAY_NAME”或“PHOTO_URL”。这会使这些值无效。
returnSecureToken 布尔值 是否返回 ID 和刷新令牌。
响应载荷
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 用户的电子邮件地址。
displayName 字符串 用户的新显示名。
photoUrl 字符串 用户的新照片网址。
passwordHash 字符串 密码的哈希版本。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
idToken 字符串 用户的新 Firebase Auth ID 令牌。
refreshToken 字符串 Firebase Authentication 刷新令牌。
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:用户凭据已失效。用户必须重新登录。

获取用户数据

您可以通过向身份验证 getAccountInfo 端点发出 HTTP POST 请求来获取用户的数据。

方法:POST

Content-Type:application/json

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

示例请求

curl 'https://identitytoolkit.googleapis.com/v1/accounts:lookup?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"idToken":"[FIREBASE_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:没有与此标识符对应的用户记录。用户可能已被删除。

您可以通过向身份验证 setAccountInfo 端点发出 HTTP POST 请求,将电子邮件/密码关联至当前用户。

方法:POST

Content-Type:application/json

端点
https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]
请求正文载荷
属性名称 类型 说明
idToken 字符串 您尝试将凭据关联到的账号的 Firebase ID 令牌。
电子邮件 字符串 要与账号关联的电子邮件。
密码 字符串 账号的新密码。
returnSecureToken 字符串 是否返回 ID 和刷新令牌。应始终为 true。
响应载荷
属性名称 类型 说明
localId 字符串 当前用户的 uid。
电子邮件 字符串 账号的电子邮件。
displayName 字符串 账号的显示名。
photoUrl 字符串 账号的照片网址。
passwordHash 字符串 密码的哈希版本。
providerUserInfo JSON 对象列表 所有包含“providerId”和“federatedId”的关联提供商对象的列表。
emailVerified 布尔值 账号的电子邮件是否已经过验证。
idToken 字符串 用户的新 Firebase Auth ID 令牌。
refreshToken 字符串 Firebase Authentication 刷新令牌。
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 状态代码表示请求成功。响应中包含 Firebase 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 个字符。

您可以通过向身份验证 verifyAssertion 端点发出 HTTP POST 请求,将 OAuth 凭据与用户关联。

方法:POST

Content-Type:application/json

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

200 OK HTTP 状态代码表示请求成功。响应包含 Firebase 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":"[FIREBASE_ID_TOKEN]","requestUri":"[http://localhost]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应包含 Firebase 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":"[FIREBASE_ID_TOKEN]","returnIdpCredential":true,"returnSecureToken":true}'

200 OK HTTP 状态代码表示请求成功。响应包含 Firebase 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:此凭据已与其他用户账号关联。

您可以通过向身份验证 setAccountInfo 端点发出 HTTP POST 请求,取消提供商与当前用户的关联。

方法:POST

Content-Type:application/json

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

示例请求

curl 'https://identitytoolkit.googleapis.com/v1/accounts:update?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"idToken":"[FIREBASE_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:用户凭据已失效。用户必须重新登录。

发送电子邮件验证

您可以通过向身份验证 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 字符串 要验证的用户的 Firebase ID 令牌。
响应载荷
属性名称 类型 说明
电子邮件 字符串 账号的电子邮件。

示例请求

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

200 OK HTTP 状态代码表示请求成功。

示例响应

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

常见错误代码

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

确认电子邮件验证

您可以通过向身份验证 setAccountInfo 端点发出 HTTP POST 请求来确认电子邮件验证码。

方法:POST

Content-Type:application/json

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

示例请求

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:没有与此标识符对应的用户记录。用户可能已被删除。

删除账号

您可以通过向身份验证 deleteAccount 端点发出 HTTP POST 请求来删除当前用户。

方法:POST

Content-Type:application/json

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

示例请求

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

200 OK HTTP 状态代码表示请求成功。

常见错误代码

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

Firebase Authentication 模拟器

Firebase Local Emulator Suite 包含一个 Authentication 模拟器,可用于 对身份验证流程进行本地原型设计和测试。模拟器公开了以下 REST 端点。

<ph type="x-smartling-placeholder">

清除用户账号

移除指定项目中的所有账号,无论其处于什么状态。

方法:DELETE

端点

请注意,9099 是 Authentication 模拟器的默认端口。检查终端 输出内容。

http://localhost:9099/emulator/v1/projects/{project-id}/accounts

获取模拟器配置

获取指定项目的模拟器专属配置。

方法:GET

端点

请注意,9099 是 Authentication 模拟器的默认端口。检查终端 输出内容。

http://localhost:9099/emulator/v1/projects/{project-id}/config
响应载荷
属性名称 类型 说明
signIn 对象 包含单个键 allowDuplicateEmails(布尔值)的 signIn 配置对象。

修补模拟器配置

更新指定项目的模拟器专用配置。

方法:PATCH

端点

请注意,9099 是 Authentication 模拟器的默认端口。检查终端 输出内容。

Content-Type:application/json

http://localhost:9099/emulator/v1/projects/{project-id}/config
请求正文载荷
属性名称 类型 说明
signIn 对象 包含单个键 allowDuplicateEmails(布尔值)的所需 signIn 配置对象。
响应载荷
属性名称 类型 说明
signIn 对象 具有单个键 allowDuplicateEmails(布尔值)的请求后登录配置对象。

检索带外身份验证码

如果您测试的身份验证流程通常会生成带外代码(例如, 电子邮件验证码、密码重置代码),则模拟器在内部存储这些代码,直到 使用它们。

方法:GET

端点

请注意,9099 是 Authentication 模拟器的默认端口。检查终端 输出内容。

http://localhost:9099/emulator/v1/projects/{project-id}/oobCodes
响应载荷
属性名称 类型 说明
oobCode 数组 一个对象数组,包含所有待处理确认码的详细信息。 每个对象均包含 email(字符串)、oobCode(字符串)、 oobLink(字符串),requestType(字符串)

检索短信验证码

如果您要测试电话/短信身份验证流程,模拟器会在内部存储此类短信代码 直到使用为止。

方法:GET

端点

请注意,9099 是 Authentication 模拟器的默认端口。检查终端 输出内容。

http://localhost:9099/emulator/v1/projects/{project-id}/verificationCodes
响应载荷
属性名称 类型 说明
验证码 数组 一个对象数组,包含所有待处理验证码的详细信息。 每个对象都包含 phoneNumber(字符串)和 sessionCode(字符串)。

错误响应

错误响应格式

无论何时从后端服务器返回上述任何 API 的错误,响应 将采用以下格式。

示例响应

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

错误代码从消息字段中获取。上述所有错误代码均指 消息字段内容。