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
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.
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:
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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:
- 1The name stays readable. That's on purpose:
piy-sops listcan show your key names and dates without unlocking anything. - 2The key itself is locked. sops scrambles only the values, with strong encryption (called AES-256). Without the master key, this is just noise.
- 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.
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.
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.
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)
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)
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.
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.
- Open a PowerShell window (it doesn't matter which folder).
- Type
piy-sops listand press Enter. - You see your key names and the date each was saved. No key values: this command never shows them.
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?
- Make sure nobody is looking at your screen and you aren't sharing it.
- In PowerShell, type
piy-sops master-keyand press Enter. A new window opens. - Copy all three lines into your safe place (for example, a new entry in your password manager app called “piy-sops master key”).
- Press Enter in that window. The screen clears, and you can close it.
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.
piy-sops list still shows every key name.piy-sops set for each new key. Then back up the new master key!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.
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.
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.
What would you do?
Pick the best answer for each situation.
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.