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-sdkDo 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
| Option | Purpose |
|---|---|
apiKey | Key string or a function returning the key for each request; defaults to PRETERNATURAL_MODEM_ADMIN_API_KEY. |
environment | production, development or local; otherwise reads PRETERNATURAL_MODEM_ENV. |
appApiUrl | App API override, ahead of PRETERNATURAL_MODEM_APP_BACKEND_URL and the environment preset. |
gatewayBaseUrl | Gateway override for model discovery and logs, ahead of PRETERNATURAL_MODEM_GATEWAY_URL and the preset. |
transport | Custom fetch, timeoutMs and default headers. |
onApiKeyExpiry | Receives 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.