Skip to Content

Server integrations

These integrations run on your server. They require privileges or credentials that must not be shipped in a browser or mobile app.

Firebase user deletion

A Firebase deletion trigger must relay its durable event ID so retries refer to the same event:

await admin.firebaseLifecycle.relayUserDeleted(projectId, { eventId: firebaseEventId, eventTime: eventTimestamp, eventType: 'user.deleted', firebaseProjectId, uid: deletedUserId, });

eventTime is the event’s timestamp, not a newly generated time for each retry. Use Firebase’s original event ID, project ID and deleted user ID. The SDK validates both the event envelope and returned receipt. The key needs customers:write for the Modem project.

The project must be configured for that Firebase identity namespace. Receiving the same event again must not create a different deletion operation. Retain the receipt when diagnosing lifecycle delivery; a successful transport response is separate from any asynchronous provider cancellation still being processed. See identity lifecycle for customer access and entitlement consequences.

Admin proxy

The optional @preternatural-js/admin-sdk/proxy subpath maps HTTP requests to admin SDK operations through your server-held key:

import { createAdminApiProxyHandler } from '@preternatural-js/admin-sdk/proxy'; export function createHandler( authenticate: (request: Request) => Promise<void>, ) { return createAdminApiProxyHandler(admin, { basePath: '/api/preternatural', authenticate, }); }

Mount the returned handler on a catch-all route for the methods your application needs. Supply an authenticate function that verifies the caller is allowed to use this server’s administrative access, and throws for every refused caller. Authentication is optional in the library: omitting it serves every request that reaches the handler. Do not publish an unguarded proxy.

The proxy validates bodies and returns the app API error envelope. It is an adapter over supported SDK operations, not an unrestricted reverse proxy to every app route. The server’s key scope still applies.

Store a 1Password integration on Modem

A remote integration stores a 1Password service account token on Modem’s server so Modem can resolve linked credential references. It differs from the local connector below. Start with an authenticated admin client; listing, retrieving and browsing need workspace secrets-integrations:read, while creation, sync and deletion need secrets-integrations:write.

Create and browse

import { createAdminClient, readAdminApiKeyFromEnv } from '@preternatural-js/admin-sdk' const apiKey = readAdminApiKeyFromEnv() if (!apiKey) throw new Error('Set PRETERNATURAL_MODEM_ADMIN_API_KEY') const serviceAccountToken = process.env.OP_SERVICE_ACCOUNT_TOKEN if (!serviceAccountToken) throw new Error('Set OP_SERVICE_ACCOUNT_TOKEN') const admin = createAdminClient({ environment: 'production', apiKey }) const integration = await admin.secretsIntegrations.create({ kind: 'onepassword-service-account', configuration: { serviceAccountToken }, metadata: { displayName: 'Production vaults' }, }) const integrations = await admin.secretsIntegrations.list() const saved = await admin.secretsIntegrations.retrieve(integration.id) const vaults = await admin.secretsIntegrations.listVaults(saved.id) const vault = vaults[0] if (vault) { const items = await admin.secretsIntegrations.listVaultItems(saved.id, vault.id) console.log(items.map(item => ({ id: item.id, title: item.title, category: item.category }))) }

Create verifies the token by listing accessible vaults before storing the integration; at least one vault must be visible. Use an actual 1Password service account token with access to the intended vaults, not the Modem admin key. List and retrieve return preview/availability fields, never the service account token. Do not log the create input.

ListVaults and listVaultItems return arrays of metadata directly, not { vaults } or { items } envelopes. The second method’s vaultId is a 1Password vault ID. It lists item summaries, not secret field contents. Choose a real item/field reference and use it in a vault-backed provider account; browsing alone does not link any credentials.

A timeout during creation does not establish whether the integration was stored. List existing integrations and inspect them before repeating creation; there is no create idempotency key or deduplication promise.

Sync and remove

For an existing integration, reuse its saved ID rather than creating another one:

const report = await admin.secretsIntegrations.sync(integration.id) if (report.superseded) { console.log('A newer sync took precedence') } else { console.log(report.targetsChecked, report.targetsUpdated) for (const failure of report.failures) { console.error(failure.target, failure.message) } } const refreshed = await admin.secretsIntegrations.retrieve(integration.id)

Sync refreshes credentials that already reference the integration, including provider accounts and supported billing/authentication provider fields. It does not import every vault item. A returned report can contain individual failures; a fulfilled promise does not mean every target changed. targetsUpdated excludes timestamp-only refreshes. Concurrent syncs are ordered so an older result cannot overwrite newer materialized credentials; superseded identifies a sync that wrote nothing. Changed references are not overwritten with values resolved for their previous references. Inspect lastSyncedAt and lastSyncError on the retrieved integration when diagnosing sync status.

Remove dependencies before unlinking. Product detachment alone leaves a vault-backed provider account referencing the integration; replace that credential source or delete the account, and update any linked billing/authentication fields first. Then explicitly delete the integration:

const removed = await admin.secretsIntegrations.delete(integration.id)

Delete returns the removed integration resource, not a boolean. The server refuses deletion with a conflict while non-deleted credentials still depend on it. Successful deletion clears Modem’s stored token and is repeatable for that same integration ID; it does not revoke the service account token at 1Password. Vault browsing and sync can still fail if permissions or provider availability change after creation. Use admin API error handling, preserve the integration ID after uncertain outcomes, and never print raw tokens or resolved secrets.

1Password connector

Install the optional @1password/sdk peer dependency where you import this subpath:

import { createOnePasswordConnector } from '@preternatural-js/admin-sdk/onepassword'; async function listCredentialItems(serviceAccountToken: string) { const connector = await createOnePasswordConnector(serviceAccountToken); const vaults = await connector.listVaults(); return Promise.all(vaults.map(vault => connector.listItems(vault.id))); }

The connector lists accessible vault/item metadata and resolves a selected op:// reference with resolveSecret(reference). Treat the connector as request-scoped; do not retain a user’s token-bearing connector across users. The optional SDK loads lazily, so importing the main admin SDK does not load its runtime.

OnePasswordError distinguishes access refusal, temporary unavailability and internal failure, and identifies the failing stage. A missing dependency is not proof the service account token was rejected. Do not log credentials or raw secret values while diagnosing.

To link a service account to Modem and have Modem resolve provider credentials, use the CLI workflow or the app’s 1Password setup. A local connector and a server-stored Modem integration are different ways to use 1Password.

API reference

Last updated on