Help › Keys, CLI and automation
API keys
On this page
There are two kinds of key. Mixing them up is the most common mistake.
| Key | Looks like | Secret? | Use |
|---|---|---|---|
| Site key | rl_site_live_... | No. It is public. | In your pages or plugin, so the loader finds your translations. |
| Secret API key | rl_sec_live_... | Yes | Servers, plugins, the command-line tool and build jobs that call the API. |
Both come in live and test forms. Use a test key while you experiment.
Create a secret key#
Admins and owners open API keys and choose Create a key. Give it a name, choose its scopes, and, if you like, limit it to one site and give it an expiry date.
The key is shown once, when you create it. We store only a hash and the first characters. If you lose it, rotate or revoke it and make a new one.
Scopes#
Give a key only what it needs. A build job that publishes needs bundles:publish, not keys:manage.
| Scope | Allows |
|---|---|
sites:read, sites:write | List, create and change sites |
strings:write | Send text found on your pages |
translations:read, translations:write | Read, export, change and import translations; run machine translation |
bundles:publish | Publish |
usage:read | Read usage |
keys:manage | Manage keys |
Other modules add scopes of their own, such as billing, webhooks and the audit log.
Rotate and revoke#
- Rotate: the new key works at once. The old one keeps working for a grace period, so you can update your tools without downtime.
- Revoke: the key stops working immediately.
Rotate and Revoke are buttons on each key. Revoke opens its own page that asks you to confirm before the key stops working. With no keys yet, the page shows an empty state with a Create a key button. The key table shows each key's start, scopes, site limit, status, expiry and when it was last used.
Rules#
- Never put a secret key in a web page, an app or a repository.
- Never send one in an email or a support ticket.
- Send it only in a request header, as
Authorization: Bearer .... - One account can have at most 50 active keys by default.
Support staff in a support session cannot see this page.