Customer API

Use the Customer API when your backend should explicitly provision customers before they connect to Mitu. Each customer record can be associated with your own customer identifier and later used with capabilities such as customer authentication and Agent Wallets.

Creating a customer does not create a wallet or fund an account. It establishes the identity record that other resources can belong to.

Create a customer

Create a customer with a stable reference from your own system.

curl --request POST \
  --url https://api.mitu.ai/v1/customers \
  --header "x-api-key: $MITU_API_KEY" \
  --header "Idempotency-Key: customer-your_user_8841" \
  --header "Content-Type: application/json" \
  --data '{
    "client_reference_id": "your_user_8841",
    "first_name": "Ada",
    "last_name": "Obi",
    "email": "ada@example.com",
    "phone": "+2348099887766"
  }'

Parameters

A successful request returns the customer record together with the connection information created for that customer.

{
  "id": "cus_ds9hazr8jd3l",
  "client_reference_id": "your_user_8841",
  "first_name": "Ada",
  "last_name": "Obi",
  "email": "ada@example.com",
  "phone": "+2348099887766",
  "key": "mcpk_3a6f9d2a6bbc816b11d524fe052b26b7e75fb7b5fa7a1a7d",
  "mcp_url": "https://mcp.yourdomain.com/mcp",
  "created_at": "2026-09-11T15:00:34.915Z"
}

Response fields

Use your own customer reference

client_reference_id connects the Mitu customer to the corresponding customer in your own application. Use an identifier that is stable and unique within your system rather than an email address or other attribute that may change over time.

For example, if your database identifies a user as your_user_8841, use that value as the customer reference. Your application can then use the same reference when reconciling supported events and customer-aware requests without making the Mitu customer ID your primary identity.

{
  "client_reference_id": "your_user_8841"
}

The Mitu cus_... identifier is still useful when calling APIs that operate directly on the customer, such as issuing an Agent Wallet. The two identifiers serve different purposes. Your reference connects the record to your application, while the Mitu ID identifies the resource within Mitu.

Customer key

The key returned when the customer is created is a customer key with the mcpk_... prefix. It can be used when that customer connects to an MCP-compatible AI client using customer-key authentication.

Treat the returned key as a credential and provide it only to the customer it belongs to. Customer keys are separate from your merchant API key and should not be used by your backend as a replacement for sk_... credentials.

See Customer keys for how customer-key authentication works.

Idempotency

Use an Idempotency-Key when creating customers so a network retry does not accidentally create the same resource more than once.

Idempotency-Key: customer-your_user_8841

Use a stable key for the same creation attempt rather than generating a new value every time you retry the request. If the API receives a repeated request with the same idempotency key, it can return the result associated with the original operation rather than processing another independent creation request.

Keep idempotency separate from client_reference_id. The idempotency key protects a specific API operation from accidental repetition, while client_reference_id connects the resulting customer to the record in your own system.

Retrieve customers

List the customers created for your account:

GET /v1/customers?limit=20

Retrieve a specific customer using its Mitu customer ID:

GET /v1/customers/{id}

Use these endpoints when your backend needs the current customer record or the customer ID required by another API operation.

Customer creation and wallets are separate

A newly created customer does not automatically have an Agent Wallet. If the customer should receive a wallet their AI agent can spend from, issue the wallet separately after the customer exists.

This separation lets your product use Mitu customer identity without requiring every customer to hold funds or use Agent Wallets.

See Agent Wallets for wallet issuance.

Related