Links

后端 API 参考

对应的官方页面地址
您的后端使用 Passwordless.dev 私有 API 来发起密钥注册、验证登录、为最终用户获取密钥等。
对此 API 发出的所有请求都要求标头中包含您的 API 私有机密以进行身份​​验证。通过 JavaScript 客户端中的方法向公共 API 发出的请求将需要您的 API 公钥

/register/token

请求

/register/token 端点发出的 POST 请求会为用户创建一个注册令牌,您的前端将使用该令牌来协商 WebAuth 凭据的创建。
请求正文至少必须包含 userIdusername,例如:
HTTP
JavaScript
POST https://v4.passwordless.dev/register/token HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
Content-Type: application/json
{
"userId": "107fb578-9559-4540-a0e2-f82ad78852f7",
"username": "[email protected]",
"displayname": "Philip J Fry",
}
const apiUrl = "https://v4.passwordless.dev";
const payload = {
"userId": "107fb578-9559-4540-a0e2-f82ad78852f7", // WebAuthn 用户句柄,应由您的应用程序生成。最多 64 字节。
"username": "[email protected]", // 用于显示目的,应帮助用户识别用户账户。
"displayname": "Philip J. Fry", // 账户的人性化名称。
"authenticatorType": "any", // WebAuthn 验证器附件模式。可以是 "any"(默认)、"platform"(触发特定于客户端设备的 Windows Hello、FaceID 或 TouchID 选项)或 "cross-platform"(触发如安全密钥等漫游选项)。
"userVerification": "preferred", // 依赖方是否要求对操作进行本地调用授权。可以是 "preferred"(默认)、"required" 或 "optional"。
"aliases": ["[email protected]"], // 用户创建的标识符(如电子邮件)数组,用于引用 userId。
"aliasHashing": true // 别名在存储之前是否应进行哈希处理。默认为 true。
};
// 使用您的 API 私有机密将 payload POST 到 Passwordless.dev API。
const { token } = await fetch(apiUrl + "/register", {
method: "POST",
body: JSON.stringify(payload),
headers: { "ApiSecret": "myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4", "Content-Type": "application/json"}
}).then(r => r.json());
除了必需的参数之外,请求正文还可能包含其他参数,所有这些参数如下:
参数
描述
示例值
userId
必填。WebAuthn 用户句柄,应由您的应用程序生成。这用于识别您的用户(可以是数据库主键 ID 或 guid)。最多 64 字节。不应包含有关用户的 PII。
"107fb578-9559-4540-a0e2-f82ad78852f7"
username
必填。用户账户标的人性化识符。它仅用于显示,帮助用户确定具有相似显示名称的用户账户之间的区别。在浏览器 UI 中使用,从不存储在服务器上。
displayname
账户的人性化名称,应由用户选择。在浏览器 UI 中使用,从不存储在服务器上。
"Philip J Fry"
attestation
WebAuthn 证书传递首选项。仅支持 "none"(默认)。
"none"(默认)
authenticatorType
WebAuthn 验证器附件模式。可以是 "any"(默认)、"platform"(触发特定于客户端设备的 Windows Hello、FaceID 或 TouchID 选项)或 "cross-platform"(触发如安全密钥等漫游选项)。
"any"(默认)
discoverable
如果为 true,则创建客户端可发现凭据,无需用户名即可登录。
true(默认)
userVerification
允许在身份验证时选择用户验证的首选项(生物识别、PIN 码等),可以是 "preferred"(默认)、"required""discouraged"
"preferred"
expiresAt
注册令牌到期的时间戳 (UTC)。默认为当前时间 +120 秒。
"3023-08-01T14:43:03Z"
aliases
userId 的别名数组,例如电子邮件或用户名。用于使用 signinWithAlias() 方法在客户端发起登录。别名对于 userId 必须是唯一的。默认为空数组 []
aliasHashing
别名在存储之前是否应进行哈希处理。默认为 true
true

响应

成功后,/register/token 端点将创建一个以 json 格式返回的注册令牌,例如:
{ "token": "register_wWdDh02ItIvnCKT_02ItIvn..."}
您的前端将使用此注册令牌来协商 WebAuth 凭据的创建。

/signin/verify

请求

/signin/verify 端点发出的 POST 请求会解压身份验证令牌,该令牌必须通过在前端调用 .signinWith*() 方法来生成(了解更多)并包含在请求正文中,例如:
HTTP
JavaScript
POST https://v4.passwordless.dev/signin/verify HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
Content-Type: application/json
{
"token": "d5vzCkL_GvpS4VYtoT3..."
}
const apiUrl = "https://v4.passwordless.dev";
// 从前端获取身份验证令牌。
const payload = { token: req.query.token };
// 使用您的 API 私有机密将身份验证令牌 POST 到 Passwordless.dev API。
const response = await fetch(apiUrl + "/signin/verify", {
method: "POST",
body: JSON.stringify(payload),
headers: { "ApiSecret": "myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4", "Content-Type": "application/json" }
});
Passwordless.dev 私有 API 将解压身份验证令牌以检查其合法性。

响应

成功后,/signin/verify 端点将返回一个成功的响应对象,例如:
{
"success": true,
"userId": "123",
"timestamp": "3023-08-01T14:43:03Z",
"rpid": "localhost",
"origin": "http://localhost:3000",
"device": "Firefox, Windows 10",
"country": "SE",
"nickname": "My Work Phone",
"expiresAt": "3023-08-01T14:43:03Z",
"tokenId": "TODO",
"type": "passkey_signin" // or passkey_register
}
使用 .success 值(truefalse)确定下一步操作,即是否完成登录(了解更多)。

/signin/generate-token

请求

/signin/generate-token 端点发出的 POST 请求可为用户手动生成一个身份验证令牌,从而避开常规的登录流程(即 .signinWith*() 方法)。生成的令牌可以通过 /signin/verify 端点进行验证,并像普通身份验证令牌一样使用。
HTTP
JavaScript
POST https://v4.passwordless.dev/signin/generate-token HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
Content-Type: application/json
{
"userId": "123"
}
const apiUrl = 'https://v4.passwordless.dev';
// 生成身份验证令牌,绕过通常的登录过程。
const payload = {
userId: '107fb578-9559-4540-a0e2-f82ad78852f7'
};
// 使用您的 API 私有机密将用户 ID POST 到 Passwordless.dev API。
const response = await fetch(apiUrl + '/signin/generate-token', {
method: 'POST',
body: JSON.stringify(payload),
headers: {
'ApiSecret': 'myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4',
'Content-Type': 'application/json'
}
});

相应

成功后,/signin/generate-token 端点将返回一个响应对象,例如:
{
"token": "d5vzCkL_GvpS4VYtoT3..."
}

/alias

请求

/alias 端点发出的 POST 请求会根据他们的 userId 向用户添加别名(了解更多),以便允许使用其他用户名、电子邮件地址等登录。
请求正文必须包含用户的 userId完整的别名数组,因为发出 POST 请求时预先存在的别名将被覆盖,例如:
HTTP
JavaScript
POST https://v4.passwordless.dev/alias HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
Content-Type: application/json
{
"userId": "107fb578-9559-4540-a0e2-f82ad78852f7",
"aliases": [
],
"hashing": true
}
const apiUrl = "https://v4.passwordless.dev";
// 获取用户现有的和新的别名数组。
const payload = {
"userId": "107fb578-9559-4540-a0e2-f82ad78852f7",
"hashing": true // 存储前是否对别名进行哈希处理,默认为 true。
};
// 使用您的 API 私有机密将数组 POST 到 Passwordless.dev API。
await fetch(apiUrl + "/alias", {
"method": "POST",
"body": JSON.stringify(payload),
"headers": { "ApiSecret": "myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4", "Content-Type": "application/json"}
});
默认情况下,"hashing": true 将在存储别名之前打开,以对其进行哈希处理。您将无法在管理控制台中查看已哈希的别名。
允许用户创建别名时需要考虑的一些规则:
  • 别名对于指定的 userId 必须是唯一的。
  • 别名长度不得超过 250 个字符。
  • 一个 userId 最多可以有 10 个与其关联的别名。

响应

任何 API 响应中都不会返回别名,并且可以对其进行哈希处理以保护用户隐私(见上文)。成功后,/alias 端点将返回 HTTP 200 OK 状态代码

/credentials/list

请求

向 /credentials/list 端点发出的 GET 请求会列出与用户关联的所有已注册凭据(由 userId 指定)。请求必须包含相关的 userId,例如:
HTTP
JavaScript
GET https://v4.passwordless.dev/credentials/list?userId=107fb578-9559-4540-a0e2-f82ad78852f7 HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
const apiUrl = "https://v4.passwordless.dev";
// 获取相关用户的 userId。
const payload = {
"userId": "107fb578-9559-4540-a0e2-f82ad78852f7"
};
// 使用您的 API 私有机密将 userId POST 到 Passwordless.dev API。
const credentials = await fetch(apiUrl + "/credentials/list", {
"method": "POST",
"body": JSON.stringify(payload),
"headers": { "ApiSecret": "myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4", "Content-Type": "application/json"}
}).then(r => r.json());

响应

成功后, /credentials/list 端点将返回 .json 对象数组,其中每个对象代表一个已注册的凭据
[
{
"descriptor": {
"type": "public-key",
"id": "2mgrJ6LPItfxbnVc2UgFPHowNGKaYBm3Pf4so1bsXSk"
},
"publicKey": "pQECAyYgASFYIPi4M0A+ZFeyOHEC9iMe6dVhFnmOZdgac3MRmfqVpZ0AIlggWZ+l6+5rOGckXAsJ8i+mvPm4YuRQYDTHiJhIauagX4Q=",
"userHandle": "YzhhMzJlNWItNDZkMy00ODA4LWFlMTAtMTZkM2UyNmZmNmY5",
"signatureCounter": 0,
"createdAt": "2023-04-21T13:33:50.0764103",
"aaGuid": "adce0002-35bc-c60a-648b-0b25f1f05503",
"lastUsedAt": "2023-04-21T13:33:50.0764103",
"rpid": "myapp.example.com",
"origin": "https://myapp.example.com",
"country": "US",
"device": "Chrome, Mac OS X 10",
"nickname": "Fred's Macbook Pro 2",
"userId": "c8a32e5b-46d3-4808-ae10-16d3e26ff6f9"
} //, ...
]

/credentials/delete

请求

/credentials/delete 端点发出的 POST 请求会删除与用户关联的特定凭证(由 credentialId 指定)。该请求必须包含相关的 credentialId,例如:
POST https://v4.passwordless.dev/credentials/delete HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
Content-Type: application/json
{
"credentialId": "qgB2ZetBhi0rIcaQK8_HrLQzXXfwKia46_PNjUC2L_w"
}

响应

成功后,/credentials/delete 端点将返回 HTTP 200 OK 状态代码

状态代码

API 会为每一个请求返回 HTTP 状态代码。
如果您收到错误,您还将收到问题详细信息形式的 JSON 序列化的错误摘要。有关详细信息,请参阅错误页面
HTTP 代码
消息
状态
200
一切正常。
201
一切正常,但空空如也。
400
错误请求。
🔴
401
您没有表明自己的身份。
🔴
409
冲突(别名已被使用)。
🔴
500
我们这边出了很大的问题。
🔴
最近更新 1mo ago