Create and manage API keys

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

1. Go to Settings, then API keys.
2. Give the key a name that will still mean something in six months - "Kindle highlights importer" rather than "test".
3. Choose the permissions it needs.
4. 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, so it cannot be shown again later, including by support. 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, and read a deck's custom fields
decks:write	Create decks, change deck settings, and add or delete custom fields
cards:read	List the cards in a deck you own
cards:write	Add, edit and delete cards in a deck you own
vocabulary:read	Look words up in your vocabulary and see what is due for review
texts:read	List and read your reading texts
texts:write	Create, edit and delete your reading texts
tables:read	List your tables and read their rows
tables:write	Create tables, change columns, add, edit and delete rows, and delete tables
notebooks:read	List your notebooks and read their pages
notebooks:write	Create notebooks, manage sections, write and delete pages, and delete notebooks
folders:read	List your folders and what is in them
folders:write	Create, rename, reorder and delete empty folders, and move items between them
languages:read	See which languages you study and which one was last active
languages:write	Add a new language to your account

Give a key the narrowest set that does the job. A script that only bulk-adds vocabulary needs cards:write alone.

Note that cards:write covers deleting as well as adding, and decks:write covers deleting a custom field - which clears that field's values on every card in the deck. There is no separate delete scope, so a key you hand to something you do not fully control can remove cards as well as create them.

If a key is missing a scope, the request fails with 403 insufficient_scope, and the message names the scope that was needed.

A key's scopes are fixed when it is created, and scopes cannot be added to an existing key. cards:read and vocabulary:read were both added after the API launched, and so were the text, table, notebook and folder scopes, so a key created before then does not have them - create a new key and revoke the old one.

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.
• Use a separate key per script, so revoking one does not break the others.

Rotating a key

Rotate in three steps, which avoids any downtime:

1. Create a new key.
2. Update your script to use it and confirm it works.
3. Revoke the old key.

You can hold up to five active keys at once.

Revoking a key

Select Revoke next to the key. It stops working on the next request. 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.