AGI01
AGI01

API 密钥管理

接口概述

API 密钥管理接口用于创建和管理 API 密钥，包括密钥生成、权限配置、使用限制等功能。

基本信息

  • 接口路径：/v1/organizations/{organization_id}/projects/{project_id}/api-keys
  • 需要认证：是
  • 请求方式：GET/POST/PUT/DELETE
  • 数据格式：JSON

API 接口

创建 API 密钥

请求

POST /v1/organizations/{organization_id}/projects/{project_id}/api-keys
Authorization: Bearer your-api-key
Content-Type: application/json

{
    "name": "开发环境密钥",
    "description": "用于开发环境测试",
    "permissions": ["chat", "embeddings"],
    "expires_at": "2025-02-01T00:00:00Z",
    "restrictions": {
        "allowed_ips": ["192.168.1.0/24"],
        "rate_limit": 100
    }
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "key_ghi789",
        "key": "zgi_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "name": "开发环境密钥",
        "description": "用于开发环境测试",
        "permissions": ["chat", "embeddings"],
        "created_at": "2024-02-01T10:00:00Z",
        "expires_at": "2025-02-01T00:00:00Z",
        "restrictions": {
            "allowed_ips": ["192.168.1.0/24"],
            "rate_limit": 100
        },
        "created_by": {
            "id": "user_123",
            "email": "user@example.com",
            "username": "username"
        }
    }
}

获取 API 密钥列表

请求

GET /v1/organizations/{organization_id}/projects/{project_id}/api-keys
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "api_keys": [
            {
                "id": "key_ghi789",
                "name": "开发环境密钥",
                "description": "用于开发环境测试",
                "permissions": ["chat", "embeddings"],
                "created_at": "2024-02-01T10:00:00Z",
                "expires_at": "2025-02-01T00:00:00Z",
                "last_used_at": "2024-02-01T11:00:00Z",
                "status": "active"
            }
        ],
        "total": 1,
        "page": 1,
        "page_size": 10
    }
}

获取 API 密钥详情

请求

GET /v1/organizations/{organization_id}/projects/{project_id}/api-keys/{key_id}
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "key_ghi789",
        "name": "开发环境密钥",
        "description": "用于开发环境测试",
        "permissions": ["chat", "embeddings"],
        "created_at": "2024-02-01T10:00:00Z",
        "expires_at": "2025-02-01T00:00:00Z",
        "restrictions": {
            "allowed_ips": ["192.168.1.0/24"],
            "rate_limit": 100
        },
        "usage": {
            "total_requests": 1000,
            "total_tokens": 50000,
            "last_used_at": "2024-02-01T11:00:00Z",
            "last_used_ip": "192.168.1.100"
        },
        "status": "active",
        "created_by": {
            "id": "user_123",
            "email": "user@example.com",
            "username": "username"
        }
    }
}

更新 API 密钥

请求

PUT /v1/organizations/{organization_id}/projects/{project_id}/api-keys/{key_id}
Authorization: Bearer your-api-key
Content-Type: application/json

{
    "name": "新密钥名称",
    "description": "新密钥描述",
    "permissions": ["chat", "embeddings", "models"],
    "restrictions": {
        "allowed_ips": ["192.168.1.0/24", "10.0.0.0/8"],
        "rate_limit": 200
    }
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "key_ghi789",
        "name": "新密钥名称",
        "description": "新密钥描述",
        "permissions": ["chat", "embeddings", "models"],
        "updated_at": "2024-02-01T12:00:00Z",
        "restrictions": {
            "allowed_ips": ["192.168.1.0/24", "10.0.0.0/8"],
            "rate_limit": 200
        }
    }
}

删除 API 密钥

请求

DELETE /v1/organizations/{organization_id}/projects/{project_id}/api-keys/{key_id}
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "message": "API 密钥已删除"
    }
}

轮换 API 密钥

请求

POST /v1/organizations/{organization_id}/projects/{project_id}/api-keys/{key_id}/rotate
Authorization: Bearer your-api-key

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "id": "key_ghi789",
        "key": "zgi_sk_yyyyyyyyyyyyyyyyyyyyyyyyyyyy",
        "previous_key": "zgi_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "rotation_date": "2024-02-01T12:00:00Z",
        "grace_period_ends": "2024-02-08T12:00:00Z"
    }
}

错误码

错误码 说明 解决方案
400 请求参数错误 检查请求参数是否符合要求
401 未授权 检查 API 密钥是否有效
403 权限不足 检查用户是否有相应的操作权限
404 API 密钥不存在 检查密钥 ID 是否正确
409 资源冲突 检查是否存在命名冲突等问题
429 请求过于频繁 遵循 API 调用限制

权限说明

可配置权限

  • chat: 对话接口权限
  • embeddings: 向量接口权限
  • models: 模型接口权限
  • files: 文件接口权限

限制选项

  • allowed_ips: IP 白名单
  • rate_limit: 请求频率限制
  • max_tokens: 最大 token 限制
  • models: 可用模型限制

使用建议

1. 密钥管理

  • 使用有意义的密钥名称
  • 设置合适的过期时间
  • 定期轮换密钥
  • 及时撤销不用的密钥

2. 安全配置

  • 配置 IP 白名单
  • 设置合理的调用限制
  • 最小权限原则
  • 监控异常使用

3. 最佳实践

  • 开发和生产环境使用不同密钥
  • 为不同服务使用独立密钥
  • 避免密钥泄露
  • 定期审查密钥使用情况