Authenticate with the API

Full API reference: developer.universally.com carries the live specification for both the Translator API and the Platform API, with every field, status code and response example. This page covers what is worth knowing around it.

Every Universally API request is authenticated with an API key passed in the X-API-Key HTTP header.

X-API-Key: your_api_key_here

Two kinds of key

They are not interchangeable, and sending the wrong one returns API_KEY_INVALID. Which one you need depends on the service you are calling.

Translating content uses the project key. Managing projects, languages and stored strings from your own tooling uses a Platform API key.

Getting a project key

A project key is generated automatically when you create a project. Open the project and go to API Settings to view, copy, or regenerate it. Viewing it needs the API keys permission. There is no endpoint for minting one.

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

Getting a Platform API key

Open the workspace and go to API Keys, then create one. See Find your API key for the fields, including the expiry and the permission list, and note that the key is shown once and cannot be retrieved afterwards.

Keeping your key safe

Your key can spend your plan’s translated words, 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

See Errors and Limits for the complete table.