Virtual Try-On API Authentication: Using an x-api-key Header Safely

Virtual try-on API authentication works by sending your key in an x-api-key header on every request, and you use it safely by making those requests from your server, never from browser code. A key in a web page can be copied by anyone who views the source.

This guide covers how the ZeDaq.ai try-on API authenticates requests and how to keep keys safe. Once the key is in place, see worked examples in Python and PHP. If you are new to the API, start with our overview of the virtual try-on API for ecommerce developers. The full reference is in the API docs.

How does the x-api-key header work?

You create a key in the ZeDaq.ai dashboard under Dashboard → API keys. You then send it with each request in the x-api-key header.

curl https://www.zedaq.ai/api/v1/size-chart?chest_cm=96 \
  -H "x-api-key: zdq_live_..."

The same header is used for the try-on endpoint, POST /api/v1/tryon. ZeDaq.ai stores keys as SHA-256 hashes, so the full key is shown once when you create it. Copy it into your secrets store at that moment.

Where should the key live?

Keep it out of your code and out of your repository.

• Environment variables on your server or hosting platform.
• A secrets manager if your host provides one.
• Never in client code. That means front-end JavaScript, mobile app bundles and public repositories.

Read the key at runtime, as in this Node.js line: process.env.ZEDAQ_API_KEY. In Python, use os.environ["ZEDAQ_API_KEY"].

Why call the API from your server?

A browser sends every request in the open. Anyone can open the network tab and read your headers. If your key is there, they can use your plan's try-ons.

A small server route solves this. Your page calls your route. Your route adds the key and calls ZeDaq.ai. The shopper never sees the key.

A minimal server route in Node.js shows the idea:

app.post("/api/tryon", async (req, res) => {
  const upstream = await fetch("https://www.zedaq.ai/api/v1/tryon", {
    method: "POST",
    headers: {
      "x-api-key": process.env.ZEDAQ_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(req.body),
  });
  res.status(upstream.status).json(await upstream.json());
});

In a real route, check the request body, limit who can call it, and add your own throttling so one visitor cannot use up your plan.

What should you protect besides the key?

The key is one of several things that can leak. Think about the whole path.

• Images. A shopper's photo is personal data. Do not log it, and do not keep it longer than you need.
• Responses. A try-on result is the shopper's own image. Show it only to that shopper.
• Logs and error pages. Make sure stack traces and debug output never print headers.
• Build tools. Some build setups copy environment variables into front-end bundles. Check that your key is not among them.
• Team access. Give the key only to people who deploy the server.

Can you lock a key to your domain?

Yes. In the dashboard you can lock a key to your domains, and requests from any other origin are refused. The docs describe this lock as required for keys used in the script-tag widget, because that key sits in your page source and unlocked keys are refused.

Use the right key for the right place:

Use	Where the key lives	Domain lock
REST API from your backend	Server environment variable	Recommended
Script-tag widget	Page source	Required

For the widget route, see embeddable widget vs API.

What does an auth error look like?

Errors return JSON in the form { "error": "code", "message": "..." }. The API docs list the codes and their messages. Handle these in your code instead of retrying blindly. The docs also say try-on usage is only charged once a render succeeds.

Log the error code, not the key. Never print the header in your logs.

What is a safe key checklist?

• Create separate keys for development and production.
• Store keys in environment variables, not source files.
• Lock widget keys to your store's domain.
• Add .env to your .gitignore.
• Remove any key that was ever pasted into a chat, ticket or commit, and create a new one.
• Limit who can read the secrets store.

If you build on WooCommerce, the same rule applies to plugins you write yourself. See virtual try-on for WooCommerce for the no-code route.

FAQs

Where do I get an API key?

Create one in the dashboard under API keys. Every paid plan has a 3-day free trial with no card required.

Can I put the key in front-end JavaScript?

Not for the REST API. Call it from your server. The script-tag widget is the only case where a key sits in page source, and it must be locked to your domain.

What if my key leaks?

Create a new key in the dashboard, switch your server to it and stop using the old one. Then check your usage for anything unexpected.

Is the key stored in plain text?

No. The API docs say keys are stored as SHA-256 hashes, so copy yours when it is shown.