API Keys

Every ONE SDK project uses two credentials to authenticate with the ONE Engine:

Credential	Visibility	Purpose
Client ID (clientId)	Public -- safe to include in client-side bundles.	Identifies your project on every API request.
Secret Key (secretKey)	Private -- never expose in client code.	Authenticates server-side requests and admin endpoints.

Obtaining Your Keys

From the Dashboard

1. Log in to dashboard.one23.io.
2. Select your project.
3. Navigate to Settings > API Keys.
4. Your clientId is always visible. Click Reveal to show the secretKey.

From the SDK

If you already have valid credentials, you can retrieve your project details programmatically:

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
}

Environment Variables

Store your credentials in environment variables. The SDK recognises the following names by convention:

.env

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

Framework-Specific Configuration

Different frameworks have different conventions for exposing environment variables to client-side code.

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 Scripts

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!,
});

Key Regeneration

If your secret key is compromised or you need to rotate keys as part of your security policy, use regenerateProjectApiKey to generate a new secret key. The old key is immediately invalidated.

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.
}

warning

Regenerating a key immediately invalidates the previous secret key. All active integrations using the old key will start receiving 401 Unauthorized responses. Coordinate key rotation with your deployment process to avoid downtime.

Key Rotation Workflow

A safe key rotation follows these steps:

1. Generate a new key using regenerateProjectApiKey or the dashboard UI.
2. Update secrets in your deployment environment (CI/CD, secrets manager, .env files).
3. Deploy the updated configuration to all running services.
4. Verify that API calls succeed with the new key.

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');

Security Best Practices

Never expose the secret key in client-side code

The secretKey must only be used in server-side environments (Node.js, edge functions, API routes). Client-side code should only use the 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
});

Use environment variables

Never hard-code credentials in source files. Always load them from environment variables or a secrets manager.

Add .env to .gitignore

.gitignore

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

Rotate keys periodically

Establish a key rotation schedule (e.g. every 90 days) as part of your security policy. Use the regenerateProjectApiKey method or the dashboard UI to automate this process.

Limit key scope by environment

Use separate projects (and therefore separate key pairs) for development, staging, and production environments. This limits the blast radius if a key is leaked.

Environment	Project Name	Engine URL
Development	my-app-dev	https://engine.one23.io
Staging	my-app-staging	https://engine.one23.io
Production	my-app-prod	https://engine.one23.io

Next Steps

• Usage & Analytics -- monitor how your keys are being used.
• Webhook Configuration -- configure event-driven notifications.
• Team Management -- control who has access to your project keys.