API Authentication

API keys

Every API request is authenticated with an API key that belongs to your account. Keys look like mk_live_ followed by 32 characters and are created in the dashboard under API keys.

We store only a SHA-256 hash of each key, so the full key is displayed once, when you create it. If you lose a key, create a new one and revoke the old one. Depending on your plan you can hold several keys at once. Using one per application or environment is a good habit.

Three ways to send your key

Pass the key in whichever way suits your HTTP client. All three are equivalent:

# 1. Query parameter
curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY"

# 2. Authorization header (Bearer token)
curl "https://metalapi.com/api/v1/latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. X-API-Key header
curl "https://metalapi.com/api/v1/latest" \
  -H "X-API-Key: YOUR_API_KEY"

Prefer a header in production. We remove the key from the query string before writing our request log, but your own logs, proxies and error trackers may keep the full URL.

A missing key returns error 101 and an unknown or revoked key returns 102, both with HTTP status 401.

Domain-restricted keys

Calling the API from client-side JavaScript exposes your key to every visitor. If you have to do it, restrict the key to your own domains in the dashboard first.

A restricted key only answers browser requests whose Origin (or Referer) header matches one of the allowed domains or their subdomains. Requests from any other website are rejected with error 107 (HTTP 403) and are not billed.

Requests without an Origin or Referer header, such as server-to-server calls from your backend, cron jobs or scripts, are always allowed. One restricted key can therefore serve both your website and your server. With example.com on the allowed list:

# Allowed: browser request from a subdomain of an allowed domain
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# Rejected with 107: origin is not on the list
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# Allowed: server-to-server request without Origin or Referer
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

Keeping keys safe

• Keep keys on the server and load them from environment variables or a secrets manager. Never commit them to Git.
• Use a separate key per application and environment, so you can revoke one without touching the others.
• If a key leaks, create a replacement, deploy it, then revoke the old key in the dashboard.
• Always call the API over https://.
• For public web pages, an embeddable widget shows live prices without any key in the page.

// Server-side only: the key never reaches the browser
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});