Server-Side Users (Advanced)

Unfederated profiles

Server-side users are not federated. Their profiles are only visible to your agents — other developers' agents cannot access them, and cross-agent profile sharing is disabled. Reads are metered at a premium rate. To unlock federation, have the user verify their phone via <configure-auth>.

When to use this

This pattern is for agents that have no user-facing frontend — CLI tools, Discord bots, Slack integrations, batch ingestion pipelines, or backend services where you already have stable user identifiers.

If your agent has any kind of web UI, use the <configure-auth> component instead. It's simpler, gives users a federated identity, and unlocks cross-agent profile sharing.

Pass your own user ID

Instead of authenticating users via phone OTP, pass your own identifier at initialization:

import { ConfigureClient } from 'configure';

const client = new ConfigureClient({
  apiKey: process.env.CONFIGURE_API_KEY,
  userId: 'your-internal-user-id',  // any stable string
});

// No token needed — all calls are scoped to this user
const profile = await client.profile.get();
await client.profile.remember(undefined, undefined, 'Prefers dark mode');
// ↑ authToken and userId resolve from client options — pass undefined to skip positional params

Configure auto-creates a profile on first contact, scoped to your developer account. The userId can be any stable string — an email, database ID, or UUID from your system.

Limitations

Capability	Federated (phone auth)	Unfederated (server-side)
Profile reads/writes	Yes	Yes
Memory extraction	Yes	Yes
Connected tools (Gmail, Calendar, etc.)	Yes	No — requires user OAuth consent
Cross-agent profile sharing	Yes	No — developer-scoped only
Visible to other developers' agents	Yes	No
Read pricing	Standard	Premium multiplier

Upgrading to federated

When you're ready to give users a full federated identity, add <configure-auth> with the external-id attribute set to the same user identifier you passed to ConfigureClient:

<configure-auth
  api-key="pk_..."
  external-id="your-internal-user-id"
></configure-auth>

When the user completes phone verification, Configure automatically merges their unfederated profile into their new federated identity:

• All memories, preferences, and context transfer to the federated profile
• Tool connections and conversation history are preserved
• Agent-specific data (under /agents/{your-agent}/) carries over
• The old unfederated profile is consumed — this is a one-way, one-time merge

After federation, the user has a single profile visible to any agent they authorize. Reads return to standard pricing.

external-id is optional

If you omit the external-id attribute, phone verification works normally but creates a fresh federated profile with no merge. Always pass external-id if the user has an existing unfederated profile you want to preserve.

See Authenticating users for the full component setup.