User credential tools

When a tool needs a static secret from the user — an API key, a personal access token, or a username/password pair — declare an authentication config with authType: "user_credentials" on the tool. IMP renders a secure credential form directly in the chat UI the first time the tool is called, stores the values encrypted at rest, and injects them into every subsequent execute call. Your code never receives an unentered form; it only runs when credentials are present.

Prerequisites

Completed Custom tools — you know how to build an ExuluTool.
Read ExuluTool — configuration — the user credentials section explains ExuluUserCredentialsConfig and CredentialField.

What IMP handles for you

When authentication is declared with authType: "user_credentials":

Credential form prompt — On the first call (and whenever stored credentials have been revoked or invalidated), IMP skips execute and returns a structured credentialRequest payload. The chat interface renders this as a typed form card — password fields are masked, help text is shown below each input.
Secure submission — When the user submits the form, the frontend posts { nonce, values } to POST /credentials/submit. The endpoint requires a valid session and cross-checks the session user against the nonce (15-minute TTL, AES-encrypted) to prevent replay attacks across users.
Encrypted storage — Values are AES-encrypted (keyed off NEXTAUTH_SECRET) and stored in the user_credentials table under (provider, userId). Plaintext never persists on disk.
Injection — On every subsequent tool call, IMP decrypts the stored row and injects credentials into inputs before calling execute. Values transit the server only — they never reach the model.
History scrubbing — The credentialRequest payload (which contains the nonce) is replaced in the model-visible conversation history with a scrub placeholder. A system guardrail also instructs the model to never ask the user to type credentials into the chat.

Your code only needs to declare the fields, optionally validate them on submission, and use inputs.credentials in execute.

What you will build

An ERP integration tool that authenticates with an API key. The key is collected once through a secure in-chat form and reused for every subsequent call.

Declare the tool with user credentials authentication

src/tools/erp-orders.ts

import { ExuluTool, CredentialInvalidError } from "@exulu/backend";
import { z } from "zod";

export const erpOrdersTool = new ExuluTool({
  id: "erp_orders",
  name: "ERP orders",
  description: "Fetches open orders from the ERP system for the signed-in user. Use this tool when the user asks about pending orders, order status, or shipment timelines.",
  type: "function",
  category: "erp",

  inputSchema: z.object({
    status: z
      .enum(["open", "shipped", "all"])
      .default("open")
      .describe("Filter orders by status."),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(20)
      .describe("Maximum number of orders to return."),
  }),

  config: [
    {
      name: "erp_base_url",
      description: "Base URL of the ERP API, e.g. https://erp.example.com/api/v2",
      type: "string",
      default: "https://erp.example.com/api/v2",
    },
  ],

  needsApproval: false,

  authentication: {
    authType: "user_credentials",
    provider:  "example_erp",          // Shared key — multiple tools can share this
    fields: [
      {
        name:        "apiKey",
        label:       "ERP API key",
        type:        "password",
        placeholder: "ek-…",
        help:        "Find your personal API key under ERP → Settings → API access.",
      },
      {
        name:        "username",
        label:       "ERP username",
        type:        "text",
        placeholder: "alice@example.com",
      },
    ],
    validate: async (values) => {
      // Called server-side when the user submits the form.
      // Throw to reject the submission — the error message is shown in the form.
      const response = await fetch("https://erp.example.com/api/v2/auth/verify", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ apiKey: values.apiKey, username: values.username }),
      });
      if (!response.ok) {
        throw new Error("API key or username is invalid. Check ERP → Settings → API access.");
      }
    },
  },

  execute: async ({ status, limit, credentials, toolVariablesConfig }) => {
    // credentials is injected by the framework when stored credentials exist.
    // If no credentials are stored, IMP never reaches execute — it returns the form instead.
    // toolVariablesConfig contains admin-supplied config values keyed by their name
    // as declared in the tool's config schema (e.g. toolVariablesConfig?.erp_base_url).
    // Hard-coded here for simplicity; swap for toolVariablesConfig?.erp_base_url when
    // you add a config schema entry for it.
    const apiBase = "https://erp.example.com/api/v2";

    const url = new URL(`${apiBase}/orders`);
    url.searchParams.set("status", status);
    url.searchParams.set("limit", String(limit));

    const response = await fetch(url.toString(), {
      headers: {
        "X-Api-Key":  credentials.apiKey,
        "X-Username": credentials.username,
        Accept:       "application/json",
      },
    });

    if (response.status === 401) {
      // Stale key — tell IMP to delete the stored row and re-prompt in this same turn.
      throw new CredentialInvalidError("example_erp", "API key rejected by upstream");
    }

    if (!response.ok) {
      return { result: JSON.stringify({ error: `ERP API returned ${response.status}` }) };
    }

    const data = await response.json();
    return { result: JSON.stringify(data.orders ?? []) };
  },
});

The credentials object injected into inputs is typed as Record<string, string> — the same shape the user submitted through the form, one key per fields[].name:

// What execute receives after the user fills in the form above
{
  credentials: {
    apiKey:   "ek-abc123…",
    username: "alice@example.com",
  }
}

Understand the credential form flow

When the agent calls erp_orders for a user who has not yet entered credentials:

IMP checks the credential store for a (example_erp, userId) row. None exists.
IMP skips execute and returns a structured short-circuit result:

{
  "credentialRequest": {
    "provider":   "example_erp",
    "fields":     [
      { "name": "apiKey",   "label": "ERP API key",  "type": "password", "placeholder": "ek-…", "help": "Find your personal API key under ERP → Settings → API access." },
      { "name": "username", "label": "ERP username", "type": "text",     "placeholder": "alice@example.com" }
    ],
    "submitUrl":  "https://your-imp-backend.example.com/credentials/submit",
    "nonce":      "<AES-encrypted claims, 15-minute TTL>"
  },
  "result": null
}

The chat interface renders a credential form card. Password fields are masked; help text appears below each input.
The user enters their API key and username and clicks Save. The frontend posts { nonce, values } to POST /credentials/submit using the current session cookie.
The submit endpoint verifies the session, decrypts the nonce (rejects if expired or tampered), cross-checks the session user against the nonce’s userId, runs the optional validate hook, then writes the AES-encrypted values to the store. Returns { ok: true }.
The agent is notified that the form was submitted and calls erp_orders again.
IMP finds the stored row, decrypts it, and injects credentials into execute.

You do not need to handle this fallback in your code — IMP manages it entirely.

Share credentials across tools

Multiple tools that access the same provider (for example, an erp_invoices tool alongside erp_orders) should share the same provider key. The user fills in the form once; all tools in the group reuse the same stored row.

src/tools/erp-invoices.ts

export const erpInvoicesTool = new ExuluTool({
  id: "erp_invoices",
  // …
  authentication: {
    authType: "user_credentials",
    provider:  "example_erp",          // Same key as erpOrdersTool
    fields: [
      { name: "apiKey",   label: "ERP API key",  type: "password" },
      { name: "username", label: "ERP username", type: "text" },
    ],
  },
  execute: async ({ credentials }) => {
    // Same stored credentials — no second form shown
    const response = await fetch("https://erp.example.com/api/v2/invoices", {
      headers: { "X-Api-Key": credentials.apiKey, "X-Username": credentials.username },
    });
    const data = await response.json();
    return { result: JSON.stringify(data.invoices ?? []) };
  },
});

When tools share a provider, they share one stored credential set per user. The fields arrays on all tools in the group must be identical (same names, same count). A mismatch causes a field-set validation error at the submit endpoint.

Self-healing with CredentialInvalidError

If the upstream API rejects the stored key (for example, the user rotated their API key in the ERP console), throw CredentialInvalidError inside execute. IMP catches it, deletes the stale stored row, and returns a fresh credential form in the same turn — no extra code required.

import { CredentialInvalidError } from "@exulu/backend";

execute: async ({ credentials }) => {
  const response = await fetch("https://erp.example.com/api/v2/orders", {
    headers: { "X-Api-Key": credentials.apiKey },
  });

  if (response.status === 401) {
    // Stale row deleted; user sees the form again immediately.
    throw new CredentialInvalidError("example_erp", "API key rejected by upstream");
  }

  // …
}

CredentialInvalidError takes two arguments: the provider string (must match authentication.provider) and an optional human-readable reason. The reason is included in the error message but is not shown directly to the user.Only throw CredentialInvalidError for the tool’s own provider. Any other error is re-thrown and surfaces as a normal tool error.

src/exulu.ts

import { erpOrdersTool }   from "./tools/erp-orders";
import { erpInvoicesTool } from "./tools/erp-invoices";

export const ready = app.create({
  // …
  tools: [erpOrdersTool, erpInvoicesTool],
});

Enable the tools in the agent workbench. No additional server configuration is required — NEXTAUTH_SECRET (already set for your IMP installation) is used as the encryption key. Make sure BACKEND is set to the backend’s public base URL so IMP can build the submitUrl in the credential form.

Security posture

Concern	How IMP handles it
At-rest encryption	Credential values are AES-encrypted with `NEXTAUTH_SECRET` before storage. The plaintext never touches disk.
Nonce replay	Each credential form carries a 15-minute AES-encrypted nonce that binds `(provider, userId, expiresAt)`. The submit endpoint cross-checks the nonce’s `userId` against the session user, so a leaked nonce cannot overwrite another user’s credentials.
Server-side injection	Values are decrypted and injected into `execute` server-side. They never appear in the tool call the model sees or in the chat history.
History scrubbing	`credentialRequest` payloads from earlier turns are replaced with a placeholder before the conversation history is forwarded to the model — the nonce and field definitions never reach the language model.
System guardrail	When any active tool has `authType: "user_credentials"`, IMP appends a system-prompt block instructing the model to never ask the user to type credentials into the chat and to ignore pasted values.

User management

Users can view and revoke their saved credentials in Settings → Connections. The interface lists every (provider, authType) pair the user has stored, with a Revoke button for each. After revocation, the next tool call that needs those credentials shows the credential form again. The same operations are available via the API (session-authenticated):

# List saved credential providers (metadata only — values are never returned)
GET /credentials

# Revoke credentials for one provider (idempotent)
DELETE /credentials/:provider

What you built

An ERP orders tool with ExuluUserCredentialsConfig that collects an API key and username through a secure in-chat form.
A validate hook that tests the credentials against the upstream API before storing them.
A CredentialInvalidError throw that triggers automatic re-prompting when the stored key is rejected.
A shared provider key so multiple ERP tools reuse the same credential set.

Next steps

ExuluTool — configuration

Full ExuluUserCredentialsConfig reference — every field, CredentialField type, and the injected credentials shape.

OAuth tools

Use the authorization-code + PKCE flow when the provider supports OAuth instead of static keys.

Custom tools

Build tools without authentication using Zod schemas and admin config params.

Tool approvals

How users see and approve tool calls in the chat interface.

Start

Tutorials

Recipes

Core classes

Reference

User credential tools

Prerequisites

What IMP handles for you

What you will build

Security posture

User management

What you built

Next steps

ExuluTool — configuration

OAuth tools

Custom tools

Tool approvals

​Prerequisites

​What IMP handles for you

​What you will build

​Security posture

​User management

​What you built

​Next steps

ExuluTool — configuration

OAuth tools

Custom tools

Tool approvals

Prerequisites

What IMP handles for you

What you will build

Security posture

User management

What you built

Next steps