后端 API 参考

您的后端使用 Passwordless.dev 私有 API 来发起密钥注册、验证登录、为最终用户获取密钥等。

对此 API 发出的所有请求都要求标头中包含您的 API 私有机密以进行身份验证。通过 JavaScript 客户端中的方法向公共 API 发出的请求将需要您的 API 公钥。

/register/token

请求

向 /register/token 端点发出的 POST 请求会为用户创建一个注册令牌，您的前端将使用该令牌来协商 WebAuth 凭据的创建。

请求正文至少必须包含 userId 和 username，例如：

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": "pjfry@passwordless.dev",
  "displayname": "Philip J Fry",
}

const apiUrl = "https://v4.passwordless.dev";

const payload = {
  "userId": "107fb578-9559-4540-a0e2-f82ad78852f7", // WebAuthn 用户句柄，应由您的应用程序生成。最多 64 字节。
  "username": "pjfry@passwordless.dev", // 用于显示目的，应帮助用户识别用户账户。
  "displayname": "Philip J. Fry", // 账户的人性化名称。
  "authenticatorType": "any", // WebAuthn 验证器附件模式。可以是 "any"（默认）、"platform"（触发特定于客户端设备的 Windows Hello、FaceID 或 TouchID 选项）或 "cross-platform"（触发如安全密钥等漫游选项）。
  "userVerification": "preferred", // 依赖方是否要求对操作进行本地调用授权。可以是 "preferred"（默认）、"required" 或 "optional"。
  "aliases": ["pjfry@passwordless.dev"], // 用户创建的标识符（如电子邮件）数组，用于引用 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());

除了必需的参数之外，请求正文还可能包含其他参数，所有这些参数如下：

参数

描述

示例值

响应

成功后，/register/token 端点将创建一个以 json 格式返回的注册令牌，例如：

{ "token": "register_wWdDh02ItIvnCKT_02ItIvn..."}

您的前端将使用此注册令牌来协商 WebAuth 凭据的创建。

请求

向 /signin/verify 端点发出的 POST 请求会解压身份验证令牌，该令牌必须通过在前端调用 .signinWith*() 方法来生成（了解更多）并包含在请求正文中，例如：

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 值（true 或 false）确定下一步操作，即是否完成登录（了解更多）。

请求

向 /signin/generate-token 端点发出的 POST 请求可为用户手动生成一个身份验证令牌，从而避开常规的登录流程（即 .signinWith*() 方法）。生成的令牌可以通过 /signin/verify 端点进行验证，并像普通身份验证令牌一样使用。

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 请求时预先存在的别名将被覆盖，例如：

POST https://v4.passwordless.dev/alias HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
Content-Type: application/json

{
  "userId": "107fb578-9559-4540-a0e2-f82ad78852f7",
  "aliases": [
    "pjfry@passwordless.dev",
    "benderrules@passwordless.dev"
  ],
  "hashing": true
}

const apiUrl = "https://v4.passwordless.dev";

// 获取用户现有的和新的别名数组。
const payload = {
    "userId": "107fb578-9559-4540-a0e2-f82ad78852f7",
    "aliases": ["pjfry@passwordless.dev", "benderrules@passwordless.dev"],
    "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，例如：

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 状态代码。

/magic-links/send

请求

向 /magic-links/send 端点发出的 POST 请求会通过 Magic Link 向提供的地址发送电子邮件。此 Magic Link 包含您提供的 URL，该 URL 会将收件人重定向到您的应用程序中的端点。从这里，您可以发送 Passwordless.dev 嵌入链接中的令牌来验证 signin/verify 处的令牌。

Passwordless.dev 不存储用户电子邮件。集成 Magic Links 时，您应该验证电子邮件和用户 ID 是否属于同一用户。否则，您可能会在应用程序中引入安全漏洞。

该请求必须包含所有三个字段。

emailAddress：Magic Link 的接收者。必须是一个有效的 E-mail 地址。
urlTemplate：这是用户单击链接时将被定向到的 URL。它应该是除令牌模板字符串 $TOKEN 之外的有效 URL。在发送电子邮件之前，我们会将 $TOKEN 与实际令牌值交换。在您的应用程序中，您应该从 URL 中解析令牌（最容易通过查询参数完成，如下所示）并将其发送到 signin/verify 端点以验证请求。
userId：电子邮件目标用户的标识符。
timeToLive：（可选）魔术链接令牌有效的秒数。如果未设置，则默认值为 1 小时。

POST https://v4.passwwordless.dev/magic-links/send HTTP/1.1
ApiSecret: myapplication:secret:11f8dd7733744f2596f2a28544b5fbc4
Content-Type: application/json

{
  "emailAddress": "user-email@example.com",
  "urlTemplate": "https://www.myapp.com?token=$TOKEN"
  "userId": "c8a32e5b-46d3-4808-ae10-16d3e26ff6f9"
  "timeToLive": 3600
}

响应

如果成功， /magic-links/send 端点将返回 HTTP 204（无内容）状态代码。

如果尚未启用 Magic Link， /magic-links/send 端点将返回 HTTP 403（未经授权）状态代码以及有关启用 Magic Link 功能的消息。

状态代码

API 会为每一个请求返回 HTTP 状态代码。

如果您收到错误，您还将收到问题详细信息形式的 JSON 序列化的错误摘要。有关详细信息，请参阅错误页面。

HTTP 代码

消息

状态

最后更新于5个月前