> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过 API 设置 Didit 身份认证

> 通过所有者批准的授权或身份认证范围的 API 密钥，在您自己的代码中为 Didit 启用登录方式、设置、品牌和防护。

Didit Authentication 可让您通过 API 启用登录方式，并读取应用的设置。请使用所有者批准的授权，或带有 `authentication` 范围的命名 API 密钥。

> [!WARNING]
>
> Authentication 是新功能。请先在沙盒应用中设置登录方式，然后再在生产应用中设置。

下文中的每个调用都发送到您应用的 Authentication 管理 API。`MANAGEMENT_BASE` 为：

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

`openapi-authentication.json` 中 `Setup` 标签下描述了相同的路由，服务端 SDK 即依据该文件重新生成。

## 选择使用哪种凭证

以下三种凭证均可使用，且每种都只能执行其所有者批准的范围内的操作。

| 凭证 | 发送方式 | 可执行的操作 |
| - | - | - |
| 带有 `authentication` 范围的命名 API 密钥 | `x-api-key: <key>` | 配置其所属的应用，并读取该应用的配置。带有 `read` 的密钥只能读取设置；带有 `write` 的密钥可以读取和修改设置。 |
| 带有 `didit:management` 的所有者批准的授权 | `Authorization: Bearer <access_token>` | 在授权同意时获批的组织范围内，并在该用户的角色权限内，配置这些组织的应用。 |
| 控制台会话 | `Authorization: Bearer <console session token>` | 根据该用户的组织成员身份和角色，读取或修改设置。终端用户视图同样需要控制台会话以及相应权限。 |

以下凭证在每个设置路由上都会返回 `403`，无论请求的内容是什么：

* 应用的**主密钥**。
* 来自 `POST /programmatic/login` 的 token，该 token 是为应用而非控制台签发的。
* 不带 `authentication` 范围的密钥，包括创建时将所有资源都设为最高级别的密钥：这些密钥会被列为完全访问权限，`scopes` 保持为空，并且不会被这些路由接受。
* 另一应用的密钥、仅带有 `didit:verification` 的授权，以及为另一组织批准的授权。

不携带任何凭证的请求会返回 `401`。授权或密钥还会受到自身限制的约束：授权受其范围、组织和用户角色的限制；密钥受其范围、IP 允许列表和过期时间的限制。

## 授权访问

### 使用具名 API 密钥

在 [Business Console](https://business.didit.me) 中打开 **Developers -> API keys**，为您正在设置的应用创建一个密钥。为它授予 `authentication` 资源的 **读取** 或 **写入** 权限：读取权限涵盖所有读取设置的调用（`GET`）；写入权限涵盖所有更改设置的调用（`POST`、`PUT`、`PATCH`、`DELETE`），并且同样可以读取设置。有关过期、IP 允许列表和轮换的说明，请参阅 [API 密钥](https://docs.didit.me/zh/console/api-keys.md)。一个密钥只属于一个应用，且仅对该应用有效。

### 通过 MCP 连接

连接到 Didit MCP 服务器的智能体，会使用其所有者在同意界面中批准的授权，权限为 `didit:management`。请参阅 [MCP 认证](https://docs.didit.me/zh/integration/mcp/authentication.md#通过-didit-登录)。

### 面向没有密码的所有者

设备代码授权（[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)）允许通过 Google、通行密钥或邮件验证码登录的所有者，在任意浏览器中批准相同的访问权限，无需输入密码。请参阅[不使用浏览器登录](https://docs.didit.me/zh/integration/mcp/authentication.md#无需浏览器登录-设备码)。

## 启用邮箱验证码

`PUT methods/{name}/` 只接受 `enabled` 参数。对于无需凭证的方法，除此之外不需要传入任何其他参数。

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

接口会返回该方法当前的状态：

```json theme={null}
{"name": "code", "enabled": true}
```

读取配置时，邮箱验证码的条目会包含 `credential_source: null`。始终开启的方法无法关闭：此类请求会返回 `{"enabled": "always_on"}`。

## 启用 Google

社交登录方式需要您自己的 OAuth 应用凭据，或者在沙盒应用上使用 Didit 的测试应用。

### 使用您自己的 Google 应用

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

在您的服务商处注册响应返回的 `callback_uri`。密钥是只写的：任何响应都不会返回它，`client_id` 是唯一可以读回的部分。如果之前没有存储过凭据，在没有凭据的情况下开启某个方式，将返回 `{"credentials": "required"}`。

### 使用 Didit 的测试应用（`didit_test`）

**沙盒应用**可以使用 Didit 自有的社交应用代替您自己的应用，足以完成设置并验证其可用性：

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` 涵盖 **Google、Microsoft、Apple 和 GitHub**，且仅适用于沙盒应用：

| 返回结果 | 适用情况 |
| - | - |
| `{"credential_source": "sandbox_only"}` | 应用处于生产环境。测试应用从不为正式登录提供服务。 |
| `{"credential_source": "unavailable"}` | 该部署没有此服务商的测试应用，因此该方式保持关闭。 |
| `200` 且 `configured: true` | 测试应用为该方式提供服务，托管登录页面会提供此方式。 |

对配置执行 `GET` 时，`didit_test_credentials` 会列出测试应用可为此应用提供服务的服务商；在生产应用上，这四个服务商的值均为 `false`。

## 读取设置结果

`GET` 请求发送到 `MANAGEMENT_BASE`，即可读取设置结果：其中包括每种方式的 `enabled` 和 `credential_source`，以及回调 URL、会话规则和注册策略。

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

已禁用的方式也会列出，因此一次 `GET` 请求即可看出哪些已开启、哪些未开启。应用的认证功能被禁用时，顶部的 `enabled` 为 `false`。此后，使用管理授权或命名密钥进行的任何设置修改都会返回 `409` 和 `{"detail": "product_disabled"}`，且不会写入任何内容。设置接口不会开启认证功能：需要有人在控制台中为该应用开启认证，之后您的调用才会生效。

## 其余设置

| `MANAGEMENT_BASE` 下的路由 | 方法 | 包含内容 |
| - | - | - |
| `settings/` | `GET`、`PATCH` | 智能体访问、组织、MFA 策略、默认成员角色、已禁用的 Webhook 事件 |
| `onboarding/` | `GET`、`PATCH` | 已完成的设置步骤，以及用户是在托管页面还是您自己的界面上登录 |
| `branding/` | `GET`、`PATCH` | 托管页面的文本和法律链接（徽标和颜色来自 Customization） |
| `protection/` | `GET`、`PATCH` | 机器人防护策略（[机器人防护](https://docs.didit.me/zh/authentication/bot-protection.md)） |
| `verified/` | `GET`、`PATCH` | 注册验证级别、升级验证规则和令牌声明 |
| `emails/`、`emails/{key}/` | `GET` | 此应用发送的登录邮件，以及渲染后的预览 |
| `domain/` | `GET`、`PUT`、`DELETE` | 托管来源和自定义登录域名 |
| `domain/verify/`、`domain/activate/` | `POST` | 检查域名的 DNS 和证书，然后将其设为规范来源 |
| `native-apps/` | `GET`、`PUT` | 共享应用通行密钥的 iOS 和 Android 应用 |

授权或密钥只能获取设置及其计数器，不能获取终端用户数据。`users/`、`sessions/`、`sign-ins/`、`overview/`、客户组织、角色、导入、智能体会话和测试邮件仍然需要控制台会话。

`agent_humans_only` 设置适用于整个应用。只有组织所有者或管理员可以更改此设置。使用具名密钥的请求会收到 `403 owner_or_admin_required`。开启此设置还需要已注册的通行密钥（`passkey_required`）。

## 错误

| 响应 | 含义 |
| - | - |
| `401` | 没有凭证。 |
| `403` | 无权配置该应用的凭证，或触及其自身限制的凭证：`ip_not_allowed`、已过期的密钥、写入路由上的只读密钥。 |
| `409 {"detail": "product_disabled"}` | 该应用的认证功能已关闭，因此使用授权或密钥进行的设置变更会被拒绝。需由人员在控制台中开启。 |
| `400 {"<field>": "<code>"}` | `sandbox_only`、`unavailable`、`not_supported`、`required`、`always_on`、`method_unavailable`、`unknown_field`。 |
| `404` | 未找到请求的资源。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.