---
title: Platform Management 快速开始
url: https://runapi.ai/zh-CN/docs/guides/platform-management/quickstart.md
canonical: https://runapi.ai/zh-CN/docs/guides/platform-management/quickstart
locale: zh-CN
---

# Platform Management 快速开始

Platform Management 让账户管理员通过 API 创建、查看、更新和撤销标准 API Key 与
Guardrail，不必每次都进入控制台操作。

## 创建 Management Key

在 [Management Keys 页面](/management_keys)创建 Management
Key，并将它与标准应用密钥分开保存。只在 Platform Management 请求中以 bearer token 形式发送它。

```http
Authorization: Bearer YOUR_MANAGEMENT_KEY
```

标准 API Key 不能调用密钥或 Guardrail 管理端点。Management Key
即使有效，如果所有者不再拥有要求的账户角色，也会收到 `403 Forbidden`。

## 列出标准 API Key

使用 `GET /api/v1/keys` 查看 Management Key 所属账户可见的密钥：

```shell
curl "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"
```

后续查询、更新、撤销或 Guardrail assignment 请求应使用返回的公开 identifier。不要根据密钥名称或 masked
token 推断访问权限。

## 创建并轮换密钥

使用 `POST /api/v1/keys` 创建应用密钥。完整 secret 只会在 create response
中返回一次，因此丢弃响应前必须把它存入密钥管理系统。轮换时先创建替代密钥，将它部署到应用并验证流量，最后再撤销旧密钥。

```shell
curl -X POST "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production worker"}'
```

## 应用 Guardrail

Guardrail 是账户级可复用策略，用于控制模型、Provider 与支出。通过 `/api/v1/guardrails` 管理策略，再使用
`/api/v1/guardrail_assignments` 绑定或移除策略。Assignment 被拒绝时，应将其作为策略或
ownership failure 处理，不能静默地在没有 Guardrail 的情况下继续。

## 处理管理错误

* `401 Unauthorized` 表示凭据缺失、格式错误、已撤销或无效。
* `403 Forbidden` 表示凭据类别或账户角色不能执行该操作。
* `404 Not Found` 表示当前已验证账户看不到请求的资源。
* `422 Unprocessable Content` 表示一个或多个提交值违反 resource rule。