Managing project keys
Each project requires a separate key to authenticate you via the API. Anyone in possession of one of these keys can perform actions only within the project to which the key belongs, and with the permissions it represents.
Developers and administrators can manage API keys from the Loco project dashboard. Click the :wrench icon: in the top-right sub-navigation. This opens the "Developer tools" window. The API keys tab is the first shown.
A simple read-only key (for exporting files) may be pre-generated for you. To add more privileged keys, click "Add key" and select a type.
Key types
When you add a new key, you are presented with these options:
- Service key (Pro accounts only) - A shared key with customizable permissions, not tied to your profile.
- Export key (read-only) - Dependent on your project access, but cannot perform write operations.
- Personal key (full access) - Operates as you with your full project privileges.
Service keys
Service keys are available on Pro accounts only.
A service key is not linked to you directly. It carries the permissions you allow, and its capabilities don't change if yours do. Other project administrators can edit or revoke it, but the secret token is not stored, and not retrievable by anyone.
If an administrator removes you from a project (or otherwise downgrades your privileges) any service keys you've created will continue to work.
Important: If you remove a developer from a project, be sure to revoke any keys they may still hold.
Export keys (read-only)
This type of key provides read only access across the API, and is intended for personal deployment scripts.
Nobody in possession of this key can do any damage to your data, because all write and delete operations are blocked.
An export key is automatically generated when you download translation files from the Loco user interface. For this reason, we store this type of key in the clear in our database.
Personal keys (full access)
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.
Keys with write access 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 rotate it to get a new one.
Important: Personal keys (including read-only ones) directly represent team members and their access to a project. If a team member's access is revoked, the key stops working. If this isn't desirable, use a service key instead.
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.
Key rotation
To regenerate a key without losing its settings, click its :rotate icon: in the Developer tools window. This regenerates only the secret token.
When rotating a service key, its identity persists to the new key also. This means that write attributions for the old key are shared with a new one. If this is undesirable, revoke the key and add a new one instead.
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 keys with write access 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 keys with write access as sensitively as passwords, and rotate them regularly;
- Use a read-only key whenever possible, especially when embedding in deployment code;
- When removing team members, revoke any keys they may possess that aren't linked to their permissions;
- Rotate or revoke keys you no longer need.