API 密钥

每个 ONE SDK 项目使用两个凭据来向 ONE Engine 进行身份验证：

凭据	可见性	用途
Client ID (`clientId`)	公开 -- 可安全包含在客户端代码中。	在每个 API 请求中标识您的项目。
Secret Key (`secretKey`)	私有 -- 切勿在客户端代码中暴露。	验证服务端请求和管理端点。

获取密钥

从仪表板获取

登录 dashboard.one23.io。
选择您的项目。
导航到 Settings > API Keys。
您的 clientId 始终可见。点击 Reveal 显示 secretKey。

从 SDK 获取

如果您已有有效凭据，可以通过编程方式获取项目详情：

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  baseUrl: process.env.ONE_ENGINE_URL!,
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

const res = await engine.getProject('proj_abc123');

if (res.success) {
  console.log('Client ID:', res.data.clientId);
  // secretKey is never returned by the API for security reasons
}

环境变量

将您的凭据存储在环境变量中。SDK 按照惯例识别以下名称：

.env
ONE_CLIENT_ID=your_client_id
ONE_SECRET_KEY=your_secret_key
ONE_ENGINE_URL=https://engine.one23.io

框架特定配置

不同的框架有不同的约定来将环境变量暴露给客户端代码。

Next.js

.env.local
# Exposed to the browser (public)
NEXT_PUBLIC_ONE_CLIENT_ID=your_client_id
NEXT_PUBLIC_ONE_ENGINE_URL=https://engine.one23.io

# Server-only (private) -- no NEXT_PUBLIC_ prefix
ONE_SECRET_KEY=your_secret_key

lib/engine.ts
import { createOneEngineClient } from '@one_deploy/sdk';

// Client-side -- no secretKey
export const clientEngine = createOneEngineClient({
  engineUrl: process.env.NEXT_PUBLIC_ONE_ENGINE_URL!,
  clientId: process.env.NEXT_PUBLIC_ONE_CLIENT_ID!,
});

// Server-side -- includes secretKey
export const serverEngine = createOneEngineClient({
  engineUrl: process.env.NEXT_PUBLIC_ONE_ENGINE_URL!,
  clientId: process.env.NEXT_PUBLIC_ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

Vite

.env
VITE_ONE_CLIENT_ID=your_client_id
VITE_ONE_ENGINE_URL=https://engine.one23.io

# Not prefixed with VITE_ -- only available server-side
ONE_SECRET_KEY=your_secret_key

src/engine.ts
import { createOneEngineClient } from '@one_deploy/sdk';

export const engine = createOneEngineClient({
  engineUrl: import.meta.env.VITE_ONE_ENGINE_URL,
  clientId: import.meta.env.VITE_ONE_CLIENT_ID,
});

React Native (Expo)

config/engine.ts
import Constants from 'expo-constants';
import { createOneEngineClient } from '@one_deploy/sdk';

const extra = Constants.expoConfig?.extra;

export const engine = createOneEngineClient({
  engineUrl: extra?.ONE_ENGINE_URL ?? 'https://engine.one23.io',
  clientId: extra?.ONE_CLIENT_ID ?? '',
});

Node.js / 服务端脚本

server/engine.ts
import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  baseUrl: process.env.ONE_ENGINE_URL!,
  clientId: process.env.ONE_CLIENT_ID!,
  secretKey: process.env.ONE_SECRET_KEY!,
});

密钥重新生成

如果您的 Secret Key 已泄露，或者您需要按照安全策略轮换密钥，请使用 regenerateProjectApiKey 生成新的 Secret Key。旧密钥将立即失效。

const res = await engine.regenerateProjectApiKey('proj_abc123');

if (res.success) {
  console.log('New Client ID:', res.data.clientId);
  console.log('New Secret Key:', res.data.secretKey);
  // Update your environment variables and secrets manager immediately.
}

注意

重新生成密钥会立即使前一个 Secret Key 失效。所有使用旧密钥的活跃集成将开始收到 401 Unauthorized 响应。请将密钥轮换与您的部署流程协调，以避免停机。

密钥轮换工作流

安全的密钥轮换遵循以下步骤：

生成新密钥 -- 使用 regenerateProjectApiKey 或仪表板 UI。
更新密钥 -- 在您的部署环境中更新（CI/CD、密钥管理器、.env 文件）。
部署 -- 将更新后的配置部署到所有运行中的服务。
验证 -- 确认 API 调用可以使用新密钥成功执行。

rotate-key.ts
import { OneEngineClient } from '@one_deploy/sdk';

async function rotateKey(projectId: string) {
  const engine = new OneEngineClient({
    baseUrl: process.env.ONE_ENGINE_URL!,
    clientId: process.env.ONE_CLIENT_ID!,
    secretKey: process.env.ONE_SECRET_KEY!,
  });

  // Step 1: Regenerate
  const res = await engine.regenerateProjectApiKey(projectId);

  if (!res.success) {
    console.error('Key rotation failed:', res.error);
    process.exit(1);
  }

  console.log('New secret key generated.');
  console.log('Client ID:', res.data.clientId);
  console.log('Secret Key:', res.data.secretKey);

  // Step 2: Verify the new key works
  const verifyEngine = new OneEngineClient({
    baseUrl: process.env.ONE_ENGINE_URL!,
    clientId: res.data.clientId,
    secretKey: res.data.secretKey,
  });

  const projectRes = await verifyEngine.getProject(projectId);

  if (projectRes.success) {
    console.log('Verification passed. Project:', projectRes.data.name);
  } else {
    console.error('Verification failed:', projectRes.error);
  }
}

rotateKey('proj_abc123');

安全最佳实践

切勿在客户端代码中暴露 Secret Key

secretKey 只能在服务端环境（Node.js、边缘函数、API 路由）中使用。客户端代码只应使用 clientId。

// Client-side -- correct
const engine = createOneEngineClient({
  engineUrl: 'https://engine.one23.io',
  clientId: 'pk_live_abc123',
  // No secretKey here
});

// Server-side -- correct
const engine = createOneEngineClient({
  engineUrl: 'https://engine.one23.io',
  clientId: 'pk_live_abc123',
  secretKey: 'sk_live_xyz789', // Only on the server
});

使用环境变量

切勿在源代码文件中硬编码凭据。始终从环境变量或密钥管理器中加载它们。

将 `.env` 添加到 `.gitignore`

.gitignore
.env
.env.local
.env.*.local

定期轮换密钥

作为安全策略的一部分，建立密钥轮换计划（例如每 90 天一次）。使用 regenerateProjectApiKey 方法或仪表板 UI 来自动化此流程。

按环境限制密钥范围

为开发、预发布和生产环境使用不同的项目（因此使用不同的密钥对）。这可以限制密钥泄露时的影响范围。

环境	项目名称	Engine URL
开发	`my-app-dev`	`https://engine.one23.io`
预发布	`my-app-staging`	`https://engine.one23.io`
生产	`my-app-prod`	`https://engine.one23.io`

下一步

用量与分析 -- 监控密钥的使用情况。
Webhook 配置 -- 配置事件驱动的通知。
团队管理 -- 控制谁可以访问您的项目密钥。

获取密钥​

从仪表板获取​

从 SDK 获取​

环境变量​

框架特定配置​

Next.js​

Vite​

React Native (Expo)​

Node.js / 服务端脚本​

密钥重新生成​

密钥轮换工作流​

安全最佳实践​

切勿在客户端代码中暴露 Secret Key​

使用环境变量​

将 .env 添加到 .gitignore​

定期轮换密钥​

按环境限制密钥范围​

下一步​