How do I authenticate with the API?

Every Universally API request is authenticated with an API key passed in the X-API-Key HTTP header. Each site has one key, a 64-character string issued from your dashboard. The key identifies which site, plan, and configuration a request belongs to. The request URL never identifies the site; the key does.

X-API-Key: your_api_key_here

The same key is accepted by every endpoint, on both the Translator and API services.

Getting your key

Your API key is generated automatically when you create a site in the Universally dashboard. Open your site settings to view, copy, or regenerate it. There is no API endpoint for minting keys; key management is done in the dashboard.

Regenerating the key immediately invalidates the previous one. Any integration using the old key will start receiving API_KEY_INVALID until you update it.

Keeping your key safe

Your key can spend your plan’s translation allowance, so treat it like a password:

• Send requests from a server, an edge function, or a backend job. Never embed the key in browser JavaScript, mobile app bundles, or any client a user can inspect.
• Keep the key out of version control. Load it from an environment variable or a secrets manager.
• If a client (a browser or app) needs translated content, route the request through your own backend so the key stays server-side.

Because the Translator allows cross-origin requests, a leaked key could be used from anywhere. If you suspect your key is exposed, regenerate it in the dashboard.

Verifying a key

To check that a key is valid and see which site it belongs to, call the verification endpoint on the API service:

curl https://api.universally.com/connect/keys/verify \
  -H "X-API-Key: your_api_key_here"

{
  "success": true,
  "data": {
    "valid": true,
    "siteId": "site_123",
    "domain": "example.com"
  },
  "message": "API key is valid.",
  "code": "KEY_VALID"
}

This is useful during setup to confirm an integration is wired to the correct site before sending real content.

Authentication errors

Code	HTTP	Meaning
API_KEY_MISSING	401	No X-API-Key header was sent.
API_KEY_INVALID_FORMAT	401	The key is not a recognized format.
API_KEY_MALFORMED	401	The key could not be parsed.
API_KEY_INVALID	401	The key is well-formed but not recognized, often after regeneration.

See Errors and Limits for the complete table.