# 身份验证

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

除了两个公开文档 [`/v1/openapi.json`](https://mcp.terra-lab.ai/v1/openapi.json) 和 [`/v1/meta/pricing`](https://mcp.terra-lab.ai/v1/meta/pricing) 之外，每次调用都需要一个 TerraLab 账户。有两种方式：代码使用 API 密钥，智能体使用 OAuth 2.1。

## API 密钥

脚本、后端和 notebook 等无法打开浏览器登录的场景，请使用密钥。

1. 在 [terra-lab.ai/login](https://terra-lab.ai/zh-CN/login) 登录。
2. 打开 [Dashboard, MCP](https://terra-lab.ai/zh-CN/dashboard/mcp)，然后选择 **Advanced**，再选择 **API keys**。
3. 给密钥命名，接受 API 条款，然后点击 **Create key**。
4. 立即复制它。密钥以 `tlk_` 开头，后面是 48 个十六进制字符，只显示一次：TerraLab 只保存哈希值，从不保存密钥本身。

在 `Authorization` 标头中发送它：

```bash
curl https://mcp.terra-lab.ai/v1/me \
  -H "Authorization: Bearer $TERRALAB_API_KEY"
```

密钥不会过期，一个账户最多可持有 20 个有效密钥。密钥泄露或项目结束时，在同一页面点击 **Revoke**：之后使用该密钥的调用会返回 `401`。用密钥发起的调用会计入创建它的账户。

不要把密钥放进源代码管理、前端代码或截图。请从环境变量或密钥管理器中读取。

## 面向智能体的 OAuth 2.1

AI 智能体通过登录获得访问权限，不使用密钥。智能体第一次不带 token 调用 `https://mcp.terra-lab.ai/mcp` 时，服务器会返回 `401`，并附带指向其元数据的 `WWW-Authenticate` 标头，随后智能体会在你的浏览器中打开 TerraLab 登录页。你确认一次，智能体就会持有一个 token。

| 项目 | 值 |
| --- | --- |
| 受保护资源元数据 | `https://mcp.terra-lab.ai/.well-known/oauth-protected-resource` |
| 授权服务器 | `https://terra-lab.ai` |
| 服务器元数据 | `https://terra-lab.ai/.well-known/oauth-authorization-server` |
| 授权类型 | 带 PKCE（`S256`）的授权码，公共客户端 |
| 客户端注册 | 动态注册，或客户端 ID 元数据文档 |
| 范围 | `data` |
| 访问 token 有效期 | 1 小时，用有效期 30 天的刷新 token 续期 |

大多数智能体会自行处理这一切：你只需粘贴服务器地址。参见 [MCP 服务器](https://terra-lab.ai/zh-CN/docs/mcp)。

OAuth 访问 token 也可以用于 REST API，同样作为 Bearer token 放在同一个标头中。

## 断开智能体

[Dashboard, MCP](https://terra-lab.ai/zh-CN/dashboard/mcp) 会列出你的 **Connected apps**。点击 **Disconnect** 会撤销该应用的访问权限：它的下一次调用会返回 `401` 和 `access_revoked`。

Source: https://terra-lab.ai/zh-CN/docs/authentication · Updated 2026-10-27