Authentication

Your API key

Create a key in the dashboard and send it as a bearer token on every call to /v1. A key belongs to one account, so every request is automatically scoped and billed to you — there’s no account ID to pass.

curl https://api.mycustomerpilot.com/v1/agents \
  -H "Authorization: Bearer mcp_sk_live_01H8XGJ..."

When do you use it?

Any time your systems talk to our API. You can set an agent up entirely in the dashboard and never touch a key — but a real integration usually needs it to:

• Report a sale for billing. When a customer pays, your payment system posts the transaction to /v1/events/transaction so we can attribute it to the conversation. This is the most common reason to hold a key.
• Send a message from your own code (/v1/messages) — an order update, a shipping notice — outside the agent’s replies.
• Manage agents, tools, and knowledge programmatically instead of clicking through the dashboard — useful once you have many, or want it in version control.
• Pull your data — conversations, contacts, metrics — into your own systems, and register webhooks to receive events.

# Your payment system tells us a sale happened, so we can
# attribute it to the conversation and bill correctly.
curl https://api.mycustomerpilot.com/v1/events/transaction \
  -H "Authorization: Bearer mcp_sk_live_01H8XGJ..." \
  -d '{ "reference": "PSK_92f1", "amount": 4500000, "currency": "NGN",
        "conversation_id": "cv_01H…" }'

Three credentials, three jobs — keep them straight

This is the part that trips people up. The API key is only one of three auth relationships, and they point in different directions with different subjects:

• Your API key — your server → our API. Proves it’s your business. This page. You always need it to operate your account with us.
• Our HMAC signature — our API → your tool endpoints. When the agent calls one of your tools, we sign the request so you can verify it’s really us. You don’t send a key here — you verify our signature (see Building tools).
• Your customer’s login — your customer → your API. When a tool must act as one of yourend users, their own login token rides inside the call. That’s about your customers, not your account (see Connect your existing login).

Why a key, and not a login for the business?

Your integration is server-to-server — code calling our API, no human at a login screen. A server runs in an environment you control, so it can safely hold one long-lived secret and present it on every request. That’s simpler and more stable than exchanging credentials for a token each time. (The dashboard at business.mycustomerpilot.comdoes use a normal browser login — but that’s our app, not something you integrate against.)

Test and live keys

Every account has two environments, and the key prefix tells them apart:

• mcp_sk_test_… — runs the full pipeline (model, retrieval, tool calls) but never sends a WhatsApp message or meters a charge. Build and iterate freely.
• mcp_sk_live_… — the real thing: real messages, real billing.

Safe retries

Writes accept an Idempotency-Key header. If a request times out and you retry it, the same key guarantees it runs once — no double-sent message and no double-charged transaction. Use a stable, meaningful value (an order ID, not a random one).

curl https://api.mycustomerpilot.com/v1/messages \
  -H "Authorization: Bearer mcp_sk_live_01H8XGJ..." \
  -H "Idempotency-Key: order-2914-confirm" \
  -d '{ "to": "2348012345678", "text": "Your order is confirmed." }'
# Retry with the SAME key after a timeout → it still sends once.

Keep keys safe