使用 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 布尔值 是否返回 ID 和刷新令牌。应始终为 true。
tenantId 字符串 用户登录的租户 ID。仅在多租户中使用。
必须与令牌中的 tenant_id 匹配。
自定义令牌声明
属性 姓名 说明
alg 算法 应为 RS256。
iss 颁发者 您项目的服务账号电子邮件地址。
sub 主题 您项目的服务账号电子邮件地址。
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。

示例请求