authentication 范围的命名 API 密钥。
下文中的每个调用都发送到您应用的 Authentication 管理 API。MANAGEMENT_BASE 为:
openapi-authentication.json 中 Setup 标签下描述了相同的路由,服务端 SDK 即依据该文件重新生成。
选择使用哪种凭证
以下三种凭证均可使用,且每种都只能执行其所有者批准的范围内的操作。
以下凭证在每个设置路由上都会返回
403,无论请求的内容是什么:
- 应用的主密钥。
- 来自
POST /programmatic/login的 token,该 token 是为应用而非控制台签发的。 - 不带
authentication范围的密钥,包括创建时将所有资源都设为最高级别的密钥:这些密钥会被列为完全访问权限,scopes保持为空,并且不会被这些路由接受。 - 另一应用的密钥、仅带有
didit:verification的授权,以及为另一组织批准的授权。
401。授权或密钥还会受到自身限制的约束:授权受其范围、组织和用户角色的限制;密钥受其范围、IP 允许列表和过期时间的限制。
授权访问
使用具名 API 密钥
在 Business Console 中打开 Developers -> API keys,为您正在设置的应用创建一个密钥。为它授予authentication 资源的 读取 或 写入 权限:读取权限涵盖所有读取设置的调用(GET);写入权限涵盖所有更改设置的调用(POST、PUT、PATCH、DELETE),并且同样可以读取设置。有关过期、IP 允许列表和轮换的说明,请参阅 API 密钥。一个密钥只属于一个应用,且仅对该应用有效。
通过 MCP 连接
连接到 Didit MCP 服务器的智能体,会使用其所有者在同意界面中批准的授权,权限为didit:management。请参阅 MCP 认证。
面向没有密码的所有者
设备代码授权(RFC 8628)允许通过 Google、通行密钥或邮件验证码登录的所有者,在任意浏览器中批准相同的访问权限,无需输入密码。请参阅不使用浏览器登录。启用邮箱验证码
PUT methods/{name}/ 只接受 enabled 参数。对于无需凭证的方法,除此之外不需要传入任何其他参数。
credential_source: null。始终开启的方法无法关闭:此类请求会返回 {"enabled": "always_on"}。
启用 Google
社交登录方式需要您自己的 OAuth 应用凭据,或者在沙盒应用上使用 Didit 的测试应用。使用您自己的 Google 应用
callback_uri。密钥是只写的:任何响应都不会返回它,client_id 是唯一可以读回的部分。如果之前没有存储过凭据,在没有凭据的情况下开启某个方式,将返回 {"credentials": "required"}。
使用 Didit 的测试应用(didit_test)
沙盒应用可以使用 Didit 自有的社交应用代替您自己的应用,足以完成设置并验证其可用性:
didit_test 涵盖 Google、Microsoft、Apple 和 GitHub,且仅适用于沙盒应用:
对配置执行
GET 时,didit_test_credentials 会列出测试应用可为此应用提供服务的服务商;在生产应用上,这四个服务商的值均为 false。
读取设置结果
GET 请求发送到 MANAGEMENT_BASE,即可读取设置结果:其中包括每种方式的 enabled 和 credential_source,以及回调 URL、会话规则和注册策略。
GET 请求即可看出哪些已开启、哪些未开启。应用的认证功能被禁用时,顶部的 enabled 为 false。此后,使用管理授权或命名密钥进行的任何设置修改都会返回 409 和 {"detail": "product_disabled"},且不会写入任何内容。设置接口不会开启认证功能:需要有人在控制台中为该应用开启认证,之后您的调用才会生效。
其余设置
授权或密钥只能获取设置及其计数器,不能获取终端用户数据。
users/、sessions/、sign-ins/、overview/、客户组织、角色、导入、智能体会话和测试邮件仍然需要控制台会话。
agent_humans_only 设置适用于整个应用。只有组织所有者或管理员可以更改此设置。使用具名密钥的请求会收到 403 owner_or_admin_required。开启此设置还需要已注册的通行密钥(passkey_required)。