Subscription setup
Use a completed native login or the sign-in choices exposed in Credentials. Modem stores subscription authentication on its servers so a relay can work independently of the original CLI files.
Import a local account
Sign in through the provider’s native CLI first. With an authenticated modem-cli target, import that login:
modem-cli subscription-signins import codex
modem-cli subscription-signins import grokThe Codex import reads auth.json from CODEX_HOME, or ~/.codex. Grok reads GROK_AUTH_PATH when set, otherwise auth.json from GROK_HOME or ~/.grok. Both commands accept --auth-file <path>.
Claude-enabled builds also provide:
modem-cli subscription-signins import claudeClaude import uses its native credential discovery, including macOS secure storage when applicable. --auth-file and --account-file select explicit credential and account metadata JSON files. Import the subscription login, not a commercial API key.
WARNING
Renewal can rotate a refresh token. Importing a login may require the original native CLI to sign in again later. Modem coordinates renewal for its stored authentication; it cannot coordinate another application’s independent use of copied credentials.
Duplicate imports
If the underlying account already exists, an interactive import offers Update existing, Add another, and Cancel. Updating preserves the selected subscription entry and its relay membership/order. Adding creates a separate selectable entry; it does not create another independent provider allowance.
Global --force chooses Add another, including in a noninteractive terminal:
modem-cli --force subscription-signins import grokWithout --force, a duplicate in a noninteractive terminal fails rather than silently updating or duplicating it. Two entries for the same underlying provider account cannot be members of the same relay group.
Import through the admin SDK
For a trusted server integration, use subscriptionSignIns.importAuthentication. Configure the admin client with workspace subscription-sign-ins:write permission. Native authentication is decoded on Modem’s server; a commercial API key is not a subscription login.
| Format | Native payload |
|---|---|
codex:auth-json | A completed Codex auth.json login |
grok:auth-json | A completed Grok auth.json login |
claude:credentials-json | Native Claude credential JSON; include accountMetadata when the credential does not carry account identity |
Read the real native files using the discovery paths above. The function below accepts their parsed JSON, not a fabricated token object. It validates the import envelope locally; Modem still checks that the payload contains a supported provider login.
import {
createAdminClient,
readAdminApiKeyFromEnv,
SubscriptionSignIn,
} from '@preternatural-js/admin-sdk'
const apiKey = readAdminApiKeyFromEnv()
if (!apiKey) throw new Error('Set PRETERNATURAL_MODEM_ADMIN_API_KEY')
const admin = createAdminClient({ environment: 'production', apiKey })
type ChooseDuplicate = (
existing: SubscriptionSignIn.Resource[],
) => Promise<SubscriptionSignIn.ImportChoice | null>
async function importNativeLogin(
nativeInput: SubscriptionSignIn.ImportInput,
chooseDuplicate: ChooseDuplicate,
): Promise<SubscriptionSignIn.Resource | null> {
const input = SubscriptionSignIn.ImportInputSchema.parse(nativeInput)
const result = await admin.subscriptionSignIns.importAuthentication(input)
if (result.status === 'imported') return result.signIn
// Present existing entries and wait for a deliberate add/update/cancel choice.
const choice = await chooseDuplicate(result.signIns)
if (choice === null) return null
const resolved = await admin.subscriptionSignIns.importAuthentication({
...input,
choice,
})
if (resolved.status !== 'imported') {
throw new Error('Account changed during import; review the current entries')
}
return resolved.signIn
}chooseDuplicate is your application’s prompt or approval UI. Return { action: 'add' } for another entry, { action: 'update', signInId: selected.id } for a selected duplicate, or null to cancel. Do not automatically select the first duplicate. Updating keeps that entry’s ID and relay memberships; adding keeps the existing entries and creates another selectable entry for the same underlying allowance. An update ID must come from the matching account entries, not an unrelated sign-in.
Pass authJson as the parsed native credential object and format from the table; Claude may also need its parsed native accountMetadata object. Do not log the input, store it in source control, or assume an arbitrary object satisfying the TypeScript envelope contains valid authentication. importCodex accepts { authJson, choice } as a convenience wrapper for the Codex format and returns the same imported/duplicate union.
Connect in the app
Open Credentials → Subscriptions → Add. The available choices start ChatGPT browser/device-code or Grok sign-in. Complete the browser/code step and return to Modem. A pending entry is not ready for relay creation. Managed Claude sign-in is not an exposed Add-menu choice in the implementation described here; use native import on a Claude-enabled deployment.
Create a link
Open a subscription’s details and create a relay, or use the CLI:
modem-cli subscription-signins list
modem-cli subscription-relays create \
--name 'Development' \
--sign-in-id '<subscription-id>'For multiple members, pass their IDs in priority order after the same --sign-in-id option. All members must be completed, signed-in subscriptions from the same provider realm. The first is primary.
Creation returns relay, relayKey and a credentialCommand. The key is shown only at creation. Save it securely. The command’s output is sensitive: do not paste it into issue reports, chat transcripts or CI logs. Later list/membership calls return a preview and non-secret setup, never the key.
For SDK automation, first install the admin SDK and create an admin key. Use a key with workspace subscription-sign-ins:write permission. CLI login does not configure the deployment or key for a separate SDK process. This example explicitly targets production; choose the deployment containing your subscriptions:
An admin SDK caller can create a link without shell parsing:
import { createAdminClient, readAdminApiKeyFromEnv } from '@preternatural-js/admin-sdk'
const apiKey = readAdminApiKeyFromEnv()
if (!apiKey) throw new Error('Set PRETERNATURAL_MODEM_ADMIN_API_KEY')
const admin = createAdminClient({ environment: 'production', apiKey })
const created = await admin.subscriptionRelays.create({
name: 'Development',
signInIds: ['<subscription-id>'],
})
// Store created.relayKey securely. Do not log the full response.
console.log(created.relay.id, created.relay.baseUrl)The admin key is server-side authentication. It is not the credential to give to Codex, Grok or Claude.
Apply the generated client setup
Use the relay response or app’s setup instructions for its exact base URL and configuration. Do not construct URLs from a provider hostname or substitute a hardcoded local port.
| Client | Generated setup |
|---|---|
| Codex | A Modem model-provider entry in ~/.codex/config.toml, Responses transport and MODEM_RELAY_KEY as its credential environment variable |
| Grok | A separate relay-specific GROK_HOME, Modem endpoints and an auth-provider command using MODEM_RELAY_KEY; then grok login and grok --no-leader |
| Claude | A separate relay-specific CLAUDE_CONFIG_DIR, ANTHROPIC_BASE_URL, relay authentication and conflicting credential/provider overrides cleared; then claude |
Keep the credential command separate from non-secret client configuration. Grok/Claude’s separate homes prevent an existing native login/configuration from silently changing the relay connection. Run setup in the shell that launches the client; environment changes do not affect an already running process.
Verify and revoke
Send a small request with a model advertised by that relay. Confirm the request appears in Usage under its project and that its outcome and serving subscription are expected. An account inspection alone does not test relay delivery.
List links or revoke a key you no longer need:
modem-cli subscription-relays list
modem-cli subscription-relays revoke --relay-id '<relay-id>'Revocation keeps the saved subscription sign-ins. To change their order without replacing the link, use membership updates.