Authentication

Send the key in the X-API-Key header. The same key works on every endpoint in the reference.

1curl "https://api.envoapi.com/api/v2/profiles/avery-chen-synthetic" \2  -H "X-API-Key: $ENVO_API_KEY"

Browser-facing apps should call your own server route, which then calls EnvoAPI with X-API-Key. Keys shipped in client-side code are public.

1export async function getProfile(publicIdentifier: string) {2  const res = await fetch(3    `https://api.envoapi.com/api/v2/profiles/${encodeURIComponent(publicIdentifier)}`,4    {5      headers: {6        "X-API-Key": process.env.ENVO_API_KEY ?? "",7      },8    },9  );1011  return res.json();12}

The same pattern in Python:

1import os2from urllib.parse import quote34import requests56def get_profile(public_identifier: str):7    res = requests.get(8        "https://api.envoapi.com/api/v2/profiles/"9        + quote(public_identifier, safe=""),10        headers={"X-API-Key": os.environ["ENVO_API_KEY"]},11        timeout=30,12    )13    return res.json()

Requests without a valid key return 401 with the standard error envelope. Do not echo API keys in logs, UI, analytics, or error messages.

1{2  "success": false,3  "data": null,4  "pagination": null,5  "meta": {6    "error": {7      "statusCode": 401,8      "type": "unauthorized",9      "detail": "Authentication required"10    }11  }12}

When a request that should be authenticated comes back 401, the cause is almost always on the sending side:

• The value of X-API-Key is the key alone — no Bearer prefix, no quotes around the value.
• An unset environment variable sends an empty header value. When debugging, log whether the header is present and non-empty — never the key itself.
• A key pasted with surrounding whitespace or a trailing line break fails. Trim the value before sending it.
• The same key works on every endpoint, so a 401 on one endpoint but not another points at the request that is missing the header — for example a second HTTP client in the codebase that never had it added.

• Store keys in environment variables or a secrets manager, not in source control.
• Use a placeholder such as $ENVO_API_KEY in documentation, scripts, and examples.
• Rotate a key immediately if it leaks, then update your server environment.