API keys: making, keeping and limiting them

A key isn't just a secret; it's the best tool you have for keeping spend under control.

6 minLesson 1 of 80 of 5 steps

An API key is a string starting with ir- that lets a tool or program talk to models on your behalf. Think of a house key: whoever holds it can walk in.

But a key here is more than a password. Each one has its own spending cap, expiry and billing source.

Rule one: one key per tool. If one gets out of hand, you close only that one.

Making a key

A key for this course0 of 5 steps

  1. Go to API keys and press New key.
  2. Give it a name that says what it's for, such as "course practice".
  3. Set Expires to 30 days. For automated tools, an expiry is safer.
  4. Fill in Monthly cap.
  5. Copy the key, keep it somewhere safe and tick the box.
New key
A key is shown in full only once, and we can't show it again. If you lose it, rotate the key.

Where the key spends from

One choice matters when you make a key:

OptionSpendsReaches
Account planThe plan's token allowanceThat plan's models
Credit (pay as you go)The wallet balanceEvery active model

This is per key and can be changed later. So you can hold a plan and still make one credit key to try a model outside it, leaving your allowance untouched.

Caps

Caps stop unwanted spending. A cap is hard: a request that would cross it doesn't run.

  • Monthly cap: in rials, over the Jalali month. It resets at the start of each month, Tehran time.
  • Daily spend cap: under More limits; resets at midnight Tehran time.
  • Daily token cap: for when you think in tokens.
  • Requests per minute: you can only lower this below your plan's limit.
Change spend cap, in a key's menu, suggests a number from the last 30 days and says when you'd reach it at this pace.

If a key leaks

Do one of these three, all from that key's menu:

ActionWhat happens
Rotate keyA new secret; the old one stops at once. The name, cap and reports stay
DisableRequests are refused immediately, but you can turn it back on
Delete keyGone for good

Where not to put a key

A key can spend from your wallet. Never put it in browser code, a mobile app or a public repository. Keep it on your own server or in an environment variable.

A quick check

Just for you: your answers aren't sent anywhere.

Your key leaked and you want to keep its name, cap and reports. What do you do?

What happens to a request that would take you past a key's monthly cap?

What you learned

  • One key per tool, with its own cap.
  • A plan key reaches the plan's models; a credit key reaches every model.
  • Next: your first request with this key.
Your first request from codeTwo values change, and that's all. By the end you'll have a real answer and seen its trace in the panel.Done, next lesson