tinykoi
All posts

API keys and rate limits: using the tinykoi API safely

· Developers · 5 min read

API key best practices start with one idea: a key is a password for a script, so treat it like one. For the tinykoi API that means: create the narrowest key that does the job, name one key per script, keep it out of your code, and rotate it by creating a new key and revoking the old one. Rate limits are counted per account, not per key, so extra keys do not buy you extra requests.

This post covers the exact behaviour: how keys look, what the scopes allow, how many you can hold and how fast you can call. If you have not made a request yet, start with the REST API quick start.

What a tinykoi API key looks like

Every key starts with tinykoi_. The fixed prefix is deliberate: leaked keys are easy to spot, and secret scanners can search for the pattern.

You create keys in Settings, in the API keys section, and not through the public API. Key management is tied to your signed-in session on purpose. A key cannot create, list or delete keys, so a leaked key cannot be used to mint more of them.

When you create a key you give it a name of up to 32 characters and choose whether it can write. The full key is shown once, in the dialog that confirms creation. tinykoi stores only a hash of it, so nobody, including us, can show it to you again. If you lose it, delete it and make another.

Afterwards the settings list shows each key's name, the first characters of the key (the tinykoi_ prefix plus four more, such as tinykoi_ab12), its access level and the date it was last used.

Read keys and write keys

There are two scopes, and they follow the HTTP method of the request:

  • Read covers every GET route: listing and fetching bookmarks, collections and tags, searching, and listing highlights.
  • Write covers every other method: creating, updating, moving, tagging and trashing. A write key can read too.

If you create a key without write access, it is read only. A read key that calls a write route gets a 403 with the message that the key lacks write access.

Pick the scope by what the script does:

  • A dashboard that shows your reading list needs read.
  • A script that saves links from a feed, or tags bookmarks, needs write.
  • A backup job that downloads your library needs read, and nothing more.

Use read keys wherever you can. If one leaks, the worst case is someone reading your library, not changing it.

Authenticating requests

Send the key as a bearer token:

Authorization: Bearer tinykoi_...

A request with no key, or a key that does not exist, gets a 401. The base path is /api/v1, and the full reference, with every route and field, is at /api/v1. It is generated from the same definitions the server uses, so it does not drift.

The public API covers bookmarks, collections, tags, search, highlights and your account details. Billing, uploads, imports and key management are not part of it.

How many keys you can hold

The number depends on your plan:

Free Pro
API keys 1 10
Requests a minute 20 120

On the free plan, creating a second key is refused until you delete the first. On Pro, you can hold up to ten, and the eleventh is refused.

Use that headroom. With ten slots, give each script its own key, named after the job, such as rss-importer or nightly-backup. When something misbehaves you can tell which one it was from the last-used date, and you can revoke it without touching the others.

Rate limits

Requests are limited per minute, and counted per account across all your keys. Free gets 20 a minute, Pro gets 120. Because the count is shared, ten keys give you the same 120 requests as one. Extra keys help you isolate scripts, not speed them up.

Every response carries three headers:

  • ratelimit-limit, the cap for your plan
  • ratelimit-remaining, how many requests you have left in the current window
  • ratelimit-reset, when the window resets

When you go over, the API answers 429, and that response also carries retry-after. Wait that long before the next request.

A well-behaved client does two things:

  1. Reads ratelimit-remaining and slows down before it reaches zero.
  2. On a 429, sleeps for retry-after and then retries.

Do not retry in a tight loop. It only keeps you at the limit.

Every response also carries an x-request-id header. Log it, so a failed call can be traced later.

API key best practices for storing keys

The usual rules apply, and they are worth repeating.

  • Never commit a key. Put it in an environment variable or a secrets manager, and add the file that holds it to your ignore list.
  • Never ship a key to a browser. The API allows cross-origin requests, which makes it convenient for scripts, but a key in front-end code is visible to everyone who opens the page. Call the API from a server or a local script.
  • Keep keys out of logs and URLs. Send the header, not a query parameter, and redact it in any request logging.
  • Do not share one key across machines. One key per script, per environment.
  • Search your repositories for tinykoi_ now and then. The fixed prefix makes this easy.

Rotating a key by revoking it

There is no expiry setting or rotate button. Rotation is create, switch, delete:

  1. Create a new key with the same name pattern and the same scope.
  2. Put it in your script's configuration and deploy.
  3. Check the settings list. The old key's last-used date should stop changing.
  4. Delete the old key.

On Pro you can hold both keys at once, so the switch has no gap. On the free plan you only get one slot, so you must delete the old key before creating the new one, and the script is without a key in between. Plan for that small gap.

If you think a key has leaked, skip the careful steps. Delete it first, then create a replacement. Deleting a key revokes it.

Rotate on a schedule that suits you, and always after someone leaves a project that had the key, or after the key appeared anywhere it should not have.

Putting it to work

With a safe key in hand, automating bookmarks with the API shows what to build. The API is included on the free plan, within the limits above, and Pro raises them. The pricing page lists both.

Sign up on the free plan, no card needed, create a read-only key and call one GET route today.