Skip to Content

Admin SDK

Use the admin SDK from a trusted server or script to manage your workspace. The customer SDK acts for one customer; the admin SDK acts with an admin API key and can issue customer tokens, change products and manage credentials.

Install

Complete package access and registry setup, then install the admin SDK:

bun add @preternatural-js/admin-sdk

Do not put registry tokens or admin API keys in client bundles. See CLI setup for building the CLI from the SDK repository.

Create a client

Create an API key in API keys, or use browser approval. Store it in PRETERNATURAL_MODEM_ADMIN_API_KEY on the server:

import { createAdminClient } from '@preternatural-js/admin-sdk'; const admin = createAdminClient({ environment: 'production' }); const projects = await admin.projects.list(); for (const project of projects) { const products = await admin.products.list(project.id); console.log(project.name, products.map(product => product.sku)); }

The key decides which resources, projects and modes the client can access. A product’s Live/Sandbox mode is separate from environment, which selects a deployment.

Configuration

OptionPurpose
apiKeyKey string or a function returning the key for each request; defaults to PRETERNATURAL_MODEM_ADMIN_API_KEY.
environmentproduction, development or local; otherwise reads PRETERNATURAL_MODEM_ENV.
appApiUrlApp API override, ahead of PRETERNATURAL_MODEM_APP_BACKEND_URL and the environment preset.
gatewayBaseUrlGateway override for model discovery and logs, ahead of PRETERNATURAL_MODEM_GATEWAY_URL and the preset.
transportCustom fetch, timeoutMs and default headers.
onApiKeyExpiryReceives a Date when a response reports a changed key expiry.

Provide an environment or resolvable service URLs. The SDK does not guess a deployment when neither is configured. Explicit URLs can include an app path prefix; gateway URLs are normalized to end in /v1.

For a rotating secret store, use an asynchronous key provider:

import { createAdminClient } from '@preternatural-js/admin-sdk'; const admin = createAdminClient({ environment: 'production', apiKey: async () => secretStore.read('modem-admin-key'), onApiKeyExpiry: expiresAt => scheduleRenewal(expiresAt), });

secretStore and scheduleRenewal are application functions. The provider runs for each request. An authenticated SDK request uses its configured key rather than an Authorization value in default transport headers. Requests do not follow redirects to another service.

Errors and recovery

import { describeApiClientError, isApiClientError, isApiClientUsageError, } from '@preternatural-js/admin-sdk'; try { await admin.projects.list(); } catch (error) { if (isApiClientError(error)) { console.error(error.code, error.requestId, error.requiredPermission); } else if (isApiClientUsageError(error)) { console.error(describeApiClientError(error)); } else { throw error; } }

ApiClientError includes status, code, and, when supplied, reason, param, requiredPermission, requestId and retryAfterSeconds. ApiClientUsageError describes local configuration or use errors; its invalid-argument subtype identifies a rejected parameter before a request is sent. Responses are schema-validated, so an unexpected server response can also surface as INTERNAL_ERROR.

A timeout or lost response does not prove a mutation failed. Read the affected resource before resubmitting a create, restore, rotation or other state change. Use durable identifiers and documented replay behavior rather than blindly retrying.

Continue with keys and permissions, resource workflows, REST conventions, logs, backup automation and server integrations.

Last updated on