Provider accounts
A provider account stores an upstream API credential. A project assignment makes that account available to a project; a product attachment selects it for a product’s requests. These are separate relationships. Subscription logins and relay links use the subscription workflow instead.
Install and configure the admin SDK, then create an admin key with accounts:read and accounts:write access to the project, plus products:write for attaching and detaching. Include the project’s Live/Sandbox mode in the key’s access. Use a product ID belonging to that project. Deployment selection (production below) is separate from the project’s mode.
Create and attach
This trusted-server example creates an OpenAI API account in an existing project. OPENAI_API_KEY must contain a real provider API key; it is separate from the Modem admin API key. Keep both on the server.
import {
createAdminClient,
ExternalServiceProvider,
readAdminApiKeyFromEnv,
} from '@preternatural-js/admin-sdk'
const apiKey = readAdminApiKeyFromEnv()
if (!apiKey) throw new Error('Set PRETERNATURAL_MODEM_ADMIN_API_KEY')
const providerKey = process.env.OPENAI_API_KEY
if (!providerKey) throw new Error('Set OPENAI_API_KEY')
const admin = createAdminClient({ environment: 'production', apiKey })
const projectId = '<project-id>'
const productId = '<product-id>'
const account = await admin.externalServiceAccounts.create(projectId, {
serviceTypeIdentifier: ExternalServiceProvider.openai,
credentialSource: 'inline',
apiKey: providerKey,
metadata: { displayName: 'Support API account' },
})
await admin.externalServiceAccounts.attachToProduct(projectId, productId, account.id)create(projectId, input) creates a project-owned account and assigns it to that project. It does not attach the account to a product; attachToProduct does that. The account inherits the project’s mode. Read responses expose apiKeyPreview and hasApiKey, not the provider secret.
For a reusable account created in Credentials, assign it to the project in the app before attaching it to a product. The current admin SDK has no standalone workspace-account creation or project-assignment method. Do not recreate an existing shared credential just to simulate an assignment.
An attachment requires an account already assigned to the same project and a product in that project. Attaching an already attached account is rejected; do not treat this create operation as an idempotent retry. A timeout can leave its outcome uncertain—inspect the product’s accounts in the app before repeating it.
Use a 1Password reference
After linking a 1Password integration, replace the inline create input with a vault-backed source:
const account = await admin.externalServiceAccounts.create(projectId, {
serviceTypeIdentifier: ExternalServiceProvider.openai,
credentialSource: 'onepassword',
secretsIntegrationId: '<integration-id>',
secretReference: 'op://<vault-id>/<item-id>/<field-id>',
metadata: { displayName: 'Support API account' },
})The identifiers are placeholders: select an actual linked integration and its secret field. Modem resolves the reference on its server; secretReference is not the API key itself. Inspect secretMaterializedAt and secretMaterializationError when diagnosing vault access. Attach the resulting account using the same product method.
Replace a credential
Updates accept the complete replacement input, not a metadata patch. For a project-owned account, provide its provider, credential source, credential and metadata again:
const replacementKey = process.env.REPLACEMENT_OPENAI_API_KEY
if (!replacementKey) throw new Error('Set REPLACEMENT_OPENAI_API_KEY')
await admin.externalServiceAccounts.update(projectId, account.id, {
serviceTypeIdentifier: ExternalServiceProvider.openai,
credentialSource: 'inline',
apiKey: replacementKey,
metadata: { displayName: 'Support API account' },
})This replaces the saved credential while retaining the account ID and attachments. Omitted metadata is replaced with an empty object. Changing the credential affects every product using that account. The project-scoped update requires project ownership; edit reusable workspace credentials from Credentials in the app.
Detach or delete
To stop one product using the account:
await admin.externalServiceAccounts.detachFromProduct(projectId, productId, account.id)Detaching removes that product relationship; the credential and project assignment remain. A missing attachment is rejected rather than silently treated as a successful detach.
To remove the account from the project:
await admin.externalServiceAccounts.delete(projectId, account.id)For a project-owned account, delete deletes the account. For a reusable workspace account assigned to the project, this removes that project’s assignment while retaining the workspace credential. Review affected product attachments before deletion; removing a credential is broader than detaching one product.
Continue with model and limit rules to configure product access. Successful creation or attachment alone does not verify that the provider accepts the key or supports a requested model; send a small customer request to verify delivery.