Installation

Install the SDK

npm

npm install configure

yarn

yarn add configure

pnpm

pnpm add configure

API keys

CLI setup

The fastest way to get an API key:

npx configure setup

This opens a browser session where you sign in with Google or GitHub, name your agent, and receive an API key. The key is saved to .env as CONFIGURE_API_KEY. (npx configure init also works as an alias.)

Agent-driven setup

If a coding agent is integrating Configure for you, it can provision your account via API — no browser needed:

1. Agent collects your phone, email, and agent name
2. Calls POST /v1/developer/provision — OTP sent to your phone
3. You provide the 6-digit code → agent calls /provision/verify
4. Agent receives keys and writes .env

See configure.dev/skill.md for the full agent-driven flow.

Manual setup

1. Sign in at platform.configure.dev
2. Create an agent and copy your API key
3. Add to your environment:

export CONFIGURE_API_KEY=sk_...

Key types

Type	Prefix	Use case	What it can do
Secret	sk_	Server-side SDK, MCP server, backend	Full API access — reads, writes, ingest, tool searches, agent CFS
Publishable	pk_	Client-side components, browser JS	OTP auth, profile reads, tool OAuth connections

Both key types work with ConfigureClient. The server enforces access — pk_ keys that call server-only endpoints get a clear 403.

Legacy keys prefixed with cfg_ continue to work with full access.

WARNING

Never expose sk_ keys in client-side code. Use publishable keys (pk_) for browser environments.

Initialize the client

import { ConfigureClient } from 'configure';

// Pass the key directly
const client = new ConfigureClient('sk_...');

// Or read from CONFIGURE_API_KEY environment variable
const client = new ConfigureClient();

If your API key has multiple agents (e.g., a monorepo with several agents), set CONFIGURE_AGENT in your environment so the SDK knows which agent is making requests:

export CONFIGURE_AGENT=your-agent-name

Or pass it directly:

const client = new ConfigureClient({ agent: 'your-agent-name' });

With a single agent, this is optional — the SDK auto-resolves it.

Authenticating users

Configure identifies users by phone number. The same phone always resolves to the same userId, regardless of which agent authenticates them. This is how profiles persist across agents.

Use the <configure-auth> web component on your frontend — it handles the entire phone OTP flow:

<script src="https://unpkg.com/configure/dist/configure-components.global.js"></script>
<configure-auth api-key="pk_..." agent="your-agent"></configure-auth>
<script>
  document.querySelector('configure-auth')
    .addEventListener('configure:authenticated', (e) => {
      const { token, userId } = e.detail;
      // Pass token + userId to your backend
    });
</script>

The component renders a phone input, sends the OTP, verifies the code, and fires configure:authenticated with { token, userId } on success. Tokens persist in localStorage across page reloads.

The returned token is a JWT valid for 30 days. The userId is a stable identifier — the same phone number always returns the same user ID across all agents.

Both values are required for all profile and tool operations. Store them securely in your application.

Server-side users (advanced)

If your agent runs entirely on the backend without a frontend, you can pass your own user identifier instead of using phone auth. This creates an unfederated profile — scoped to your developer account only, invisible to other agents, with no cross-agent sharing.

See the Server-Side Users guide for details and limitations.

Demo token

For development, you can skip the OTP flow and get a demo token:

const token = await client.auth.getDemo();
// Use this token for development — it creates a temporary demo user

TIP

Demo tokens are for development only. In production, always use the OTP flow so users get a persistent identity tied to their phone number.

Next steps

Quick Start — Add Configure to your existing agent with profile.get() + CONFIGURE_TOOLS. You control the LLM, the prompt, the tools. Configure is your data layer.