Create and manage API keys
Create an API key in settings, choose what it is allowed to do, and revoke it when you no longer need it.
An API key is how a script proves it is acting on your behalf. Anyone holding the key can do anything the key's permissions allow to your account, so treat it like a password.
Creating a key
- Go to Settings, then API keys.
- Give the key a name that will still mean something in six months - "Kindle highlights importer" rather than "test".
- Choose the permissions it needs.
- Select Create key.
Your email address must be verified before you can create a key. If it is not, the page will tell you, and you can resend the verification email from email verification.
Copy it immediately
The key is shown once, at the moment you create it. Yalango stores only a one-way hash of it, which means there is genuinely no way to show it to you again later - not through support either. If you lose it, revoke the key and create a new one.
A key looks like this:
yal_kZ8fQ2mXp4LvNc7BhRt1WsYd6JgEaU3oPi9TnMbVxQk
Permissions
Each key carries a set of permissions, called scopes. A key only gets the access you tick.
| Scope | What it allows |
|---|---|
decks:read | List your decks |
decks:write | Create decks and change deck settings |
cards:write | Add cards to a deck you own |
Give a key the narrowest set that does the job. A script that only bulk-adds vocabulary needs cards:write alone, and then a leaked key cannot rename or create anything.
If a key is missing a scope, the request fails with 403 insufficient_scope, and the message names the scope that was needed.
Keeping a key safe
- Store it in an environment variable or a secrets manager, never in a file you commit.
- Never put it in front-end code. The API sends no CORS headers partly to make this impossible by accident.
- Use a separate key per script, so revoking one does not break the others.
Rotating a key
There is no rotate button, because doing it in two steps means no downtime:
- Create a new key.
- Update your script to use it and confirm it works.
- Revoke the old key.
You can hold up to five active keys at once, which leaves room for this.
Revoking a key
Select Revoke next to the key. It stops working on the very next request - there is no cache to wait out. Anything still using it will start getting 401 revoked_api_key.
Revoking is permanent. The key stays in the list marked as revoked so you can see it existed.
When keys stop working
Beyond revoking, a key stops working if you schedule your account for deletion. Keys are removed entirely when the account is purged.