Managing authentication keys
Each project requires a separate key to authenticate you via the API. Anyone in possession of one of these keys can perform actions as you, but only within the project to which the key belongs.
You can manage API keys from your Loco project dashboard at any time. Click the :wrench icon: in the top-right project. This opens the "Developer tools" window.
You can create as many keys as you need — for example, one key per CI/CD pipeline or environment. Keys can be given optional labels to help you identify them.
1. Read-only API key
Intended for deployment scripts; this type of key provides read only access across the API. It's also used from the Loco interface when you download translation files.
Nobody in possession of this key can do any damage to your data, because write and delete operations are blocked when a key has no write access.
We store read-only keys in the clear in our database, so you can retrieve them from the Developer tools window at any time.
Despite being read-only, this key should not be distributed publicly. It can be used to access any content in a project that its owner can access.
2. Full access API key
This key provides read and write access to a Loco project across the API. For this reason you should treat it as you would your password. Anyone in possession of this key can update and delete your project data as if they were you.
If you plan to distribute your key into a deployment script, consider firstly whether write operations are required. If writes are required, avoid committing the key into code repositories and such.
Full access keys are not stored in our database. This means you can't retrieve them once you close the Developer tools window. Be sure to copy new keys to a secure location of your own. If you lose your key, you'll have to revoke it and create a new one.
Important: API keys are associated with project members and their access permissions therein. If a team member is removed, the key will stop working.
Revoking keys
To permanently disable a key, click its :trash icon: in the Developer tools window. Revoked keys stop working immediately and can't be restored. A revoked key can never be reissued to another user.
You don't need to know the key value to revoke it, but for secret keys (shown as masked values) you can optionally enter the full key to verify it before removal. If the key doesn't match, it won't be revoked.
To rotate a key, simply add a new one and revoke the old one.
Authentication and usage
Loco keys are bearer tokens. This means there's no need to sign requests or present any additional secret information.
- API endpoints can be authenticated by a query string
"key"parameter, or as an Authorization header. See the API docs. - We recommend that full access keys are always sent in the header as
"Authorization: Bearer <key>". - For backward compatibility, the string "Loco" can be used in place of "Bearer".
Security notes
- The Loco API operates only over SSL. Be sure to verify secure connections;
- Treat your keys as sensitively as passwords and rotate them regularly;
- Use a read-only key whenever possible, especially when embedding in deployment code;
- Rotate or revoke keys you no longer need.