Server-Side Users

Server-side users let you create and operate on Configure profiles with your own stable user IDs. No phone verification, hosted auth component, or browser hot-path integration is required up front.

This creates an unlinked profile: a developer-scoped profile that your backend can read and update through the SDK or raw HTTP API with a server-side sk_... key. The user can link it to a phone number later, which upgrades it into a federated Configure profile.

Developer-scoped until linked

Unlinked profiles are visible only inside your developer account. Other developers' agents cannot read them, connected tools require hosted user OAuth, and cross-developer profile sharing is unavailable until the user completes phone verification with Configure.auth({ externalId }). Unlinked reads are metered at a premium rate.

When to use this

Use server-side users when:

• your product already has authenticated users and stable internal IDs
• you want profile reads/writes before adding Configure-hosted UI
• your agent is a CLI, Discord bot, Slack bot, background worker, or API-only service
• you are backfilling profiles from a CRM, database, support logs, or conversation history
• you want to adopt Configure without putting auth or components in the chat hot path

Use hosted Configure.auth() when:

• the user needs a federated identity they can carry across developers' agents
• the user needs Gmail, Calendar, Drive, or Notion connections
• another agent should be able to read this user's profile after user approval
• you are ready to let the user own and review the profile directly

These are not mutually exclusive. Start with X-User-Id, then link later with externalId.

SDK usage

Pass userId when constructing the server-side client with your secret key. The SDK sends it as X-User-Id on profile requests.

import { ConfigureClient } from 'configure';

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

const profile = await client.profile.get();
await client.profile.remember(undefined, undefined, 'Prefers dark mode');
await client.profile.ingest(undefined, undefined, {
  text: 'Senior designer. Prefers concise answers. Vegetarian.',
  sync: true,
});

You can also pass the external user ID per call:

const profile = await client.profile.get(undefined, 'user_42');
await client.profile.remember(undefined, 'user_42', 'Prefers window seats');

No user auth token is required for profile reads, memory writes, or ingest when userId resolves through X-User-Id, but the client must use a server-side secret key.

Direct HTTP usage

The raw API shape is the same:

curl "https://api.configure.dev/v1/profile?user_id=user_42" \
  -H "X-API-Key: sk_..." \
  -H "X-User-Id: user_42"

Configure resolves (developer_account, user_42) to an internal profile UUID, auto-creates it on first contact, and auto-approves the calling agent for that developer-scoped profile.

See Direct HTTP API for endpoint examples, raw Configure File System (CFS) writes, and batch ingestion. CFS is Configure's path-addressed storage layer behind composed Memory Profiles.

Capabilities

Capability	Federated profile	Unlinked profile
Read composed profile	Yes	Yes
Save memories with remember()	Yes	Yes
Ingest conversations or text	Yes	Yes
Batch seed profiles	Yes	Yes
Direct CFS reads	Yes, permission-filtered	Yes, developer-scoped
Direct CFS writes	Own agent namespace only	Developer-scoped profile paths and own agent namespace
Connected tools	Yes, after OAuth	No, requires hosted user OAuth
Other developers' agents can read after user approval	Yes	No
Read pricing	Standard	Premium multiplier

Link later

When you are ready to federate a server-side user, mount hosted auth with the same external ID:

<div id="auth"></div>
<script src="https://configure.dev/js/configure.js"></script>
<script>
  Configure.auth({
    el: "#auth",
    publishableKey: "pk_...",
    agent: "your-agent",
    externalId: "your-internal-user-id",
    theme: "light"
  });
</script>

When the user completes phone verification, Configure merges the unlinked profile into the phone-linked profile:

• memories, preferences, and profile documents move to the federated user
• agent-specific data under /agents/{your-agent}/ carries over
• future reads use standard federated pricing
• the user can approve other agents and connect tools normally

The merge is one-way. If you omit externalId, phone verification still works, but it creates or resolves a separate federated profile instead of merging the unlinked one.

Production checklist

• Use a stable ID that will not be recycled across people.
• Keep CONFIGURE_API_KEY on the server only.
• Set CONFIGURE_AGENT or pass agent when a developer account has multiple agents.
• Do not put X-User-Id in browser code as a substitute for your own auth; the unlinked-user path requires sk_....
• Link with externalId before relying on connected tools or cross-developer profile sharing.