Authentication & Security Guide

Every request to the AIVA API is authenticated with an API key, sent in the X-API-Key header, scoped to your merchant account.

curl https://api.getaiva.ai/api/merchant/info \
  -H "X-API-Key: $AIVA_API_KEY"

Getting your credentials

You need two values:

1. API key - your secret. Treat it like a password.
2. Merchant ID - your store's identifier (a GUID). Not secret, but required.

Both come from the AIVA Merchant Dashboard: Settings → API Keys → Generate New Key. Name the key for where it will be used ("Claude Desktop", "n8n production") so you can rotate or revoke it later without guesswork.

The key is shown once, at creation. Store it somewhere safe immediately; if you lose it, revoke it and generate a new one. Full walkthrough: API Key Management.

Using credentials

Direct API - send the key on every request:

const res = await fetch('https://api.getaiva.ai/api/customers', {
  headers: { 'X-API-Key': process.env.AIVA_API_KEY },
});

MCP server - the key and merchant ID go in the environment of your MCP config, never in the prompt:

{
  "mcpServers": {
    "aiva": {
      "command": "npx",
      "args": ["-y", "@getaiva/mcp"],
      "env": {
        "AIVA_API_KEY": "YOUR_API_KEY",
        "AIVA_MERCHANT_ID": "YOUR_MERCHANT_ID",
        "AIVA_API_BASE_URL": "https://api.getaiva.ai"
      }
    }
  }
}

Automation tools (n8n, Zapier, Make) - store the key in the tool's credential vault and reference it in the HTTP header, exactly as the direct API example.

The rules that keep you safe

• Server-side only. Never ship an API key in browser JavaScript, a mobile app binary, or a public repo. If a key must be near the front end, proxy the call through your own backend.
• Environment variables, not source code. AIVA_API_KEY belongs in your deployment environment or secret manager, never committed to git.
• One key per integration. Separate keys for your dashboard, your automations and your experiments mean a leak only burns one door, and rotation doesn't break everything at once.
• Rotate on departure or suspicion. Someone leaves the team, a laptop goes missing, a key appears in a log: revoke and reissue. It takes a minute.
• Least privilege by scope. Give each integration the narrowest access it needs.

Transport and rate limiting

All API traffic is HTTPS only; plain HTTP is refused. Requests are rate-limited per key: back off on 429 responses rather than retrying immediately, and batch reads where the endpoint supports it.

A note on what Aiva will not do

Security is also structural on the conversation side: Aiva qualifies and books, she does not give regulated advice, and escalation paths mean a human sees anything outside her lane. The same principle applies to the API - if an endpoint would need your customers' payment credentials, it does not exist. Payments stay with your payment provider.

Questions, or found something that looks off? Talk to us - security reports get read first.