REST API

These routes manage client API keys through an internal admin experience.

• Admin auth header: include x-admin-key: ADMIN_API_KEY on every route.
• Backend prerequisite: define ADMIN_API_KEY=your-key in the DB backend .env before calling these routes.
• List: returns masked metadata only.
• Create: returns masked metadata plus the raw apiKey once.
• Rotate: returns masked metadata plus the replacement raw apiKey once.
• Delete: permanently removes the client key.

GET    /admin/api-keys
POST   /admin/api-keys
GET    /admin/api-keys/:id
PATCH  /admin/api-keys/:id
POST   /admin/api-keys/:id/rotate
DELETE /admin/api-keys/:id

The create and update routes accept a name, active flag, and optional expiry date. The rotate route only needs the admin header.

async function createApiKey() {
  const response = await fetch('/api/admin/api-keys', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-admin-key': ADMIN_API_KEY,
    },
    body: JSON.stringify({
      name: 'Main Frontend Key',
      isActive: true,
      expiresAt: null,
    }),
  });

  if (!response.ok) {
    throw new Error(`Failed to create API key: ${response.status}`);
  }

  return response.json();
}

async function updateApiKey(id: number) {
  const response = await fetch(`/api/admin/api-keys/${id}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'x-admin-key': ADMIN_API_KEY,
    },
    body: JSON.stringify({
      name: 'Backup Key',
      isActive: false,
      expiresAt: null,
    }),
  });

  if (!response.ok) {
    throw new Error(`Failed to update API key: ${response.status}`);
  }

  return response.json();
}

async function rotateApiKey(id: number) {
  const response = await fetch(`/api/admin/api-keys/${id}/rotate`, {
    method: 'POST',
    headers: {
      'x-admin-key': ADMIN_API_KEY,
    },
  });

  if (!response.ok) {
    throw new Error(`Failed to rotate API key: ${response.status}`);
  }

  return response.json();
}

type CreateApiKeyRequest = {
  name?: string;
  isActive?: boolean;
  expiresAt?: string | null;
};

type UpdateApiKeyRequest = {
  name?: string;
  isActive?: boolean;
  expiresAt?: string | null;
};

Create and rotate responses expose the raw key once. Later list and get operations expose only masked or prefixed values.

• Raw key handling: save apiKey immediately because the backend may not return it again.
• Masked list responses: treat maskedKey and keyPrefix as display-only metadata.
• Client usage: send the saved raw key later as x-api-key on protected business routes.

type ApiKeyRecord = {
  id: number;
  name: string;
  keyPrefix: string;
  maskedKey: string;
  isActive: boolean;
  expiresAt: string | null;
  lastUsedAt: string | null;
  createdAt: string;
  updatedAt: string;
};

type CreateOrRotateApiKeyResponse = {
  message: string;
  apiKey: string;
  key: ApiKeyRecord;
};

Handle these backend outcomes explicitly in the client admin experience.

• 401/403: missing or invalid x-admin-key.
• 404 Not Found: requested key record does not exist.
• 400 Bad Request: invalid create or update payload.
• One-time raw key: create and rotate are the only reliable moments to capture the full client key.

The created client key is meant for protected business routes, not for calling admin endpoints.

• Admin routes: always use x-admin-key.
• Business routes: use the created client key as x-api-key.

async function getSymbolFolders() {
  const response = await fetch('/api/symbol/folders', {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
  });

  if (!response.ok) {
    throw new Error(`Failed to load folders: ${response.status}`);
  }

  return response.json();
}