Skip to Content

Resource workflows

Create one admin client and pass parent IDs before child IDs. For example, admin.products.retrieve(projectId, productId) retrieves one product; there is no global product selection stored on the client.

Projects and products

import { Project } from '@preternatural-js/admin-sdk'; const project = await admin.projects.create({ name: 'Support assistant', sandboxMode: true, authenticationProvider: Project.AuthenticationProvider.none, metadata: { customServerURL: null, freeUsersAllowed: true }, }); const products = await admin.products.list(project.id);

Choose the project’s authentication and billing configuration deliberately. Read identity setup and product configuration before allowing real customer access. projects.update accepts changed fields; project mode is not an update field.

The resource groups are:

ResourceOperations
projectsList, retrieve, create, update, delete.
externalBillingProvidersEnable, update and disconnect billing, with revision checks and explicit credential selection.
productsList, retrieve, create, update, delete and discover configured models.
externalServiceAccountsList, retrieve, create, update, delete, attach to product, detach from product.
usageLimitRules, rateLimitRulesList, create and update product rules.
customersList, create Sandbox customers, update/delete and issue native-authentication sessions.
productGrantsCreate a manual product grant for a customer.
subscriptionSignIns, subscriptionRelaysInspect subscription accounts and manage relay links/membership.
modelsList the public gateway catalog.
starredItemsList/add/move/remove workspace sidebar items.

REST endpoints include additional individual-rule retrieval/deletion and bulk rule deletion. SDK method coverage and server route coverage are not identical.

Provider credentials

Follow provider account setup for complete create, assign, attach, replace and detach workflows.

An external service account supplies an upstream provider credential; attaching it to a product makes it available to that product. Creating a credential does not automatically attach it everywhere. Inline credential input and a linked 1Password reference are separate credential sources. Read responses contain previews, not the upstream secret.

Use 1Password integration to keep references stable and resolve them on Modem’s server. Replacing an account’s credential source affects its uses; deleting an assignment differs from deleting the underlying credential. Review the deletion result and dependent product assignments before removing credentials.

Usage and rate rules

import { BilledResourceRules } from '@preternatural-js/admin-sdk'; const rule = await admin.usageLimitRules.create(projectId, productId, { allowanceValue: 100, allowanceMetric: BilledResourceRules.UsageRuleAllowanceMetric.numberOfRequest, scopeKind: BilledResourceRules.UsageRuleScopeKind.modelIdentifier, scopeValue: modelId, });

Update with the complete rule input; do not assume omitted fields retain their values:

await admin.usageLimitRules.update(projectId, productId, rule.id, { allowanceValue: 200, allowanceMetric: rule.allowanceMetric, scopeKind: rule.scopeKind, scopeValue: rule.scopeValue, });

Rate rules additionally select minute, hour or day. Changing a rate allowance does not replenish the separate total usage allowance. See gateway errors for refusals and retry behavior.

products.listConfiguredModels(projectId, productId) reads both rule sets plus the public gateway catalog. Exact model rules contribute their IDs; regex rules contribute matching catalog IDs. An invalid regex contributes no matches. This is a view of configured rules, not proof that a provider credential can serve a model. Subscription-native availability is discovered through the relay catalog. For native login payloads and explicit duplicate choices, see programmatic subscription import.

Customers and grants

const customer = await admin.customers.createSandbox(projectId, { name: 'Test customer', email: 'test@example.com', }); await admin.customers.update(projectId, customer.id, { isSuspended: true });

Suspension refuses further customer access; reinstatement does not repair a revoked identity provider login. For production identity, configure a provider and establish customer sessions through the customer SDK. Trusted-server native authentication is also available:

const session = await admin.customers.registerWithNativeAuthentication(projectId, { metadata: { authProvider: 'my-app', authId: appUserId }, });

Registering the same application authId reuses its customer. logInWithNativeAuthentication(projectId, { customerId }) issues tokens for an existing customer. Both operations require customers:write; never expose that key or a session for an arbitrary customer to an untrusted caller.

const grant = await admin.productGrants.create(projectId, customerId, { product: productId, endsAt: '2027-01-01T00:00:00.000Z', });

Omit endsAt for one product billing interval; null is valid only for an infinite product. The default product and an already-active grant of the same product are refused. This is a manual entitlement, not a recorded purchase. Payment refunds and cancellation use the billing lifecycle instead.

Starred items

await admin.starredItems.add(`project:${projectId}`); await admin.starredItems.add(`product:${productId}`, { position: 'below', anchor: `project:${projectId}`, }); await admin.starredItems.move(`project:${projectId}`, { position: 'first' }); await admin.starredItems.remove(`product:${productId}`);

Stars form one ordered workspace list. Add/remove are idempotent; adding an existing item without placement does not move it. Move requires an already-starred item. Workspace reach is required.

API reference

Last updated on