身份认证

所有 Archyl API 请求都需要使用 API 密钥进行身份认证。本指南介绍如何创建和使用 API 密钥。

创建 API 密钥

登录您的 Archyl 账户
前往 个人资料 > API 密钥
点击 创建 API 密钥
配置您的密钥：
- 名称：一个描述性名称（例如"CI/CD 流水线"、"本地开发"）
- 权限：只读或读写
- 过期时间：可选的过期日期
点击创建
立即复制并保存密钥 — 之后将无法再次查看

API 密钥权限

权限	功能
读取	查看项目、元素、文档和架构数据
写入	创建、更新和删除项目、元素和文档

请选择满足您需求的最小权限。

使用 API 密钥

在每个请求的 X-API-Key 头中包含您的 API 密钥：

curl -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

示例：列出项目

curl -X GET \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

示例：创建系统

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Service",
    "description": "Handles payment processing",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

MCP 服务器身份认证

使用 MCP 服务器与 AI 助手配合时，身份认证方式相同：

Claude Code / Claude Desktop

将您的 API 密钥添加到 MCP 配置中：

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Cursor

在 .cursor/mcp.json 中：

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

安全最佳实践

保护您的密钥

切勿将 API 密钥提交到版本控制系统
在 CI/CD 流水线中使用环境变量
定期轮换密钥
为不同环境使用不同的密钥

环境变量

# 存储在 .env 中（添加到 .gitignore）
ARCHYL_API_KEY=your-api-key

# 在脚本中使用
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

CI/CD 集成

将您的 API 密钥作为密钥存储在 CI/CD 平台中：

GitHub Actions：

- name: Update Architecture
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI：

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

管理 API 密钥

查看密钥

前往 个人资料 > API 密钥 查看所有活跃密钥：

密钥名称和创建日期
权限级别
过期状态
最后使用时间

撤销密钥

撤销已泄露或未使用的密钥：

前往 个人资料 > API 密钥
找到要撤销的密钥
点击撤销
确认操作

撤销的密钥将立即失效。

密钥过期

密钥可以设置过期时间：

永不过期：密钥在手动撤销之前一直有效
30 天：适用于临时访问
90 天：兼顾安全性和便利性
自定义：设置任意过期日期

错误响应

无效或缺失的密钥

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

HTTP 状态码：401 Unauthorized

权限不足

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have write permissions"
  }
}

HTTP 状态码：403 Forbidden

密钥已过期

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key has expired"
  }
}