Learn It Yourself
All courses · Dashboard › API Keys & Passwords
Learn It YourselfSafetyBeginner

API Keys & Passwords

Your tools use API keys to talk to online services, and each key is worth real money. This course explains, in plain words, what a key is, how to keep its power small, why keys get replaced, and how your own password manager, piy-sops, keeps them all locked away.

Beginner 11 lessons 2 try-it-yourself steps 10 practice goals

What you'll learn

  • What an API key is, and what a service does when one arrives
  • Why a key should only be allowed to do what your tool needs
  • What “rotating” a key means, and why computers do it better than people
  • How piy-sops keeps every key in one locked file
  • Where to keep your master key, and how to back it up
  • Why losing the master key is a nuisance, not a disaster
How each lesson works
1. ReadA short, plain explanation with an everyday comparison.
2. PractisePretend exercises on this page. No real keys are used anywhere.
3. Tick it offFinished exercises get a tick. Progress also shows on your dashboard.
No real keys on this page

Every key you see here is made up. Two small steps happen in your real terminal, and neither of them shows a key in the chat.

Lesson 01Reading

What an API key is

An API is the door a service opens for other programs. Replicate's website is for you; Replicate's API is for your tools. When your image tool asks Replicate to make a picture, it goes through that door.

An API key is the password your tool shows at that door. It's a long string of random characters, made for you on the service's website, for example:

r8_3fK9xQ2mLpV7wT1cZ8nB4yH6dR0sJ5aE (made up)

Your password

You type it into a login page. You chose it, you remember it, and often a code on your phone is needed too.

An API key

A program sends it with every request. The service made it, nobody remembers it, and there's no phone check: the key alone is enough.

Think of a hotel key card

The front desk gives you a card. Whoever taps it on the door gets in: the lock doesn't check faces. An API key works the same way, which is why the rest of this course is about keeping the card safe and keeping its power small.

Lesson 02Practice

How a service checks a key

Every time your tool asks for something, it sends the key along, tucked in a hidden part of the message. Then the service does four quick checks:

1Is there a key?No key, no entry.
2Do I know it?It's compared with the service's list of keys. Unknown or deleted keys are turned away.
3Who is it?The key points to one account: yours. That account pays.
4Is this allowed?Each key has rights. Asking for more than the key allows is refused.

The answer comes back with a number. You may see these in error messages: 200 means “OK”, 401 means “I don't know this key”, and 403 means “I know you, but this key isn't allowed to do that”.

A nice detail: many services keep only a scrambled fingerprint of your key, not the key itself. That's why a website shows a new key only once: after that, even the service can't show it to you again.

Practise: you're the tool. Send each of the four requests to the pretend front desk and read the answer.

Pick a request above to send it.
Seen 0 of 4 answers.
Lesson 03Reading

Whoever holds the key is you

Look back at the four checks: none of them asks who is holding the key. If someone else gets a copy, the service treats them as you. They can use your account, and you get the bill.

Keys don't usually get stolen by hackers breaking in. They leak through small, ordinary slips:

  • pasted into a chat (with Claude or anyone else), where it stays in the history,
  • written into a code file that later goes to GitHub,
  • visible in a screenshot or a screen share,
  • sent by email or saved in a notes app.
If a key leaks, replace it

Deleting the message or the file isn't enough: copies may already exist. Make a new key, switch to it, and delete the old one on the service's website. That's called rotation (Lesson 05). Once the old key is deleted, every copy of it is useless.

What you already have in place

Claude follows your piy-sops rules: it never asks you to paste a key, and never shows one. When a key is needed, a separate window opens where you type it hidden. And piy-sops check can search a project for leaked keys.

Lesson 04Practice

Only the rights it needs

A hotel card opens your room and the gym, not every room in the building. If you lose it, the damage stays small. Keys work best the same way. Security people call this least privilege: give each key only the rights its job needs.

Many services let you choose when you make a key. Cloudflare, for example, asks which parts of your account the key may touch and whether it may only look or also change things. Other useful choices, where a service offers them:

  • One key per tool, so you can replace one without breaking the others. In piy-sops, a key named after a project (like my-app_replicate_main) is used by that project only.
  • A spending limit on the account, so a leaked key can't run up a huge bill.
  • An end date, so a forgotten key switches itself off.

Practise: you're making a key for a small photo backup tool. Its only job: upload new photos to your storage account. Tick the rights the key should have, then press Make the key.

Lesson 05Practice

Rotation: changing the locks

Rotating a key means swapping it for a new one and switching the old one off. It's a password change, done for a program.

People are bad at this. Forced to change a password every few months, most of us pick something easy and change one digit: Summer2025! becomes Autumn2025!. That's why the US standards body NIST now advises against forcing people to change passwords on a schedule, and asks for a change when there's a sign of trouble.

Computers have none of those problems. A new key is completely random, nobody has to remember it, and the swap takes seconds. That's why large companies let their systems rotate keys automatically, often every few weeks or even every few hours. A stolen key then stops working soon, even if nobody noticed the theft.

When to rotate your own keys

Right away when a key may have leaked (for example, you pasted it into a chat). Now and then for old keys: piy-sops list marks keys saved more than a year ago with “old: consider replacing”. And when you stop using a tool, delete its key on the website.

Practise: a rotation done in the wrong order can break your tool for a while. Click the four steps in the right order.

Lesson 06Reading

piy-sops: one locked file

piy-sops is your own small password manager for API keys. It's built on two free, widely used tools:

  • sops locks and unlocks the file.
  • age made your master key, the one key that opens the lock.

All your keys live in one file called keys.sops.json, in your piy-sops project. Here's a simplified look inside, with a made-up key:

  1. 1The name stays readable. That's on purpose: piy-sops list can show your key names and dates without unlocking anything.
  2. 2The key itself is locked. sops scrambles only the values, with strong encryption (called AES-256). Without the master key, this is just noise.
  3. 3The lock's own notes. They record which master key can open the file, plus a seal: if anyone changes even a name by hand, sops notices and refuses to open it.
Why it can safely go to GitHub

Because the keys inside are locked, the file can be backed up to your private GitHub like any other file. piy-sops does this by itself every time you save a key. Only that one file is ever uploaded.

How a tool gets a key

Your tool asks piy-sops get replicate. piy-sops finds the master key, unlocks just that one value, and hands it straight to the tool. The key never appears on screen, in the chat or in your code.

Lesson 07Try it yourself

piy-sops: one master key

Your master key, made by age, comes in two halves that belong together, like a padlock and its key:

The padlock (public half)

age1ql3z7hjy54pw3h…

Starts with age1. It can only lock. It's written in the locked file's notes, and it's fine if someone sees it.

The key (secret half)

AGE-SECRET-KEY-1…

Starts with AGE-SECRET-KEY-1. It's the only thing that can unlock. This is the part to protect and back up.

Both halves live together in one small text file of three lines, outside every project:

That place, %APPDATA%\sops\age\keys.txt, is where sops looks for an age key on Windows by default. On your computer it's C:\Users\mate\AppData\Roaming\sops\age\keys.txt. Because it's outside your projects, it can never end up on GitHub by accident.

One master key for everything

You don't need a password for each API key. One master key opens the one file that holds them all. That's what makes it simple, and why the backup in the next lesson matters.

Try it yourselfPowerShellnot done yet
  1. Open a PowerShell window (it doesn't matter which folder).
  2. Type piy-sops list and press Enter.
  3. You see your key names and the date each was saved. No key values: this command never shows them.
Lesson 08Try it yourself

Where to keep the master key

Right now your master key exists in one place: your computer. If the computer breaks or is replaced, that copy is gone. So keep one backup somewhere that isn't this computer, and keep it private.

The command piy-sops master-key opens a separate window that shows the three lines, so you can copy them. The key never appears in the chat with Claude. Copy all three lines, and press Enter in that window when you're done: it clears the screen.

Practise: is each place a good home for your master key backup?

Try it yourselfPowerShellnot done yet
  1. Make sure nobody is looking at your screen and you aren't sharing it.
  2. In PowerShell, type piy-sops master-key and press Enter. A new window opens.
  3. Copy all three lines into your safe place (for example, a new entry in your password manager app called “piy-sops master key”).
  4. Press Enter in that window. The screen clears, and you can close it.
Lesson 09Reading

Lost it? Not the end of the world

First the honest part: without the master key, nobody can open the locked file. Not you, not Claude, not a thief. age has no back door and no “forgot my password” button. That's exactly what makes it safe.

Now the good part: the locked file only holds copies. The real keys come from your accounts at Replicate, Cloudflare and the rest, and you can always log in there and make new ones. Even better, the names in the locked file aren't locked, so piy-sops list still tells you exactly which services to visit.

1See what you hadpiy-sops list still shows every key name.
2New keysOn each service's website, make a new key and delete the old one.
3Fresh startAsk Claude to set up a new master key and an empty locked file.
4Save againpiy-sops set for each new key. Then back up the new master key!
An afternoon, not a disaster

And you get a bonus: every key is now brand new, so it's also a full rotation. Step 3 needs Claude's help on purpose: piy-sops refuses to make a new master key while the old locked file is still there, so it can never quietly lock you out of keys you still have.

New computer, backup in hand?

Then nothing is lost at all. Put the three lines back into %APPDATA%\sops\age\keys.txt (Claude can do it with you), get the piy-sops project from GitHub, and everything opens as before.

The one case that does need action

If someone else may have your master key and the locked file, assume they can read every key. Rotate all of them, and make a new master key.

Lesson 10Quiz

What would you do?

Pick the best answer for each situation.

Lesson 11Reference

Cheat sheet and common questions

piy-sops commands

piy-sops list
key names and dates
piy-sops set name
save or replace a key (hidden window)
piy-sops master-key
show the master key to back it up
piy-sops check project
look for leaked keys

Words in this course

API key
a password for programs
Least privilege
only the rights it needs
Rotation
new key in, old key off
Master key
the one key that opens the locked file

Golden rules

Never
paste a key into a chat or a code file
Small
one key per tool, only the rights it needs
Leaked?
rotate it, don't just delete the message
Backup
master key in one safe place off this computer

Where things are

Locked file
piy-sops\keys.sops.json, also on your private GitHub
Master key
%APPDATA%\sops\age\keys.txt, never on GitHub
Backup
your password manager, paper or a USB stick at home
Is it bad that the locked file is on GitHub?

No. The values inside are locked, so without the master key the file is useless to anyone who sees it. Keeping it on GitHub means you also have a backup of the file itself. Your piy-sops repository is private on top of that.

Can Claude see my keys?

Claude never asks you to paste one and never shows one. When it needs a key to test something, it hands piy-sops get straight to the command that uses it, so the value doesn't appear in the chat.

Why can't I just keep my keys in a text file?

A plain text file can be read by anything that opens it, and one wrong save puts it in a project folder and on GitHub. The locked file can't be read without the master key, so a slip there does no harm.

Should I change my keys every month?

No need. Replace a key right away if it may have leaked, and consider replacing keys that are more than a year old (piy-sops list marks them).

I read about “sops rotate”. Is that the same thing?

Related idea, different lock. Inside the locked file, sops uses a hidden working key; sops rotate swaps that one. It doesn't change your API keys at the services. Your rotations happen on the service's website plus piy-sops set.

What's the difference between my master key and my GitHub password?

The GitHub password lets you into GitHub, where the locked file is stored. The master key opens the locked file itself. Someone would need both the file and the master key to read your API keys.