API key

A key is written for machines. It does not expire on its own, it carries only the rights you ticked at creation, and one leaked key is a single line to revoke instead of a password everyone has to change.

An API key is a long random string a program sends instead of a password to act on one account.

Why a program needs its own key

A password belongs to a person. It comes with a second factor, a session that ends and a device that has to be present.

A script has none of that. It runs at three in the morning on a machine nobody is looking at, and a code prompt stops it dead.

It lives until you end it
No daily sign in and nothing to type. The key is the whole of the credential.
It is narrower than a person
A person can do everything their role allows. A key does only what was ticked for it.
It has a name of its own
One key per contractor or per script is one line to close when that arrangement ends.

Rights a key carries

Rights are chosen at creation and cannot be widened later. A key that reads profiles cannot touch a proxy or mark a browser as running.

Right	What it opens
profiles:read	The profile list.
profiles:write	Create, edit and delete a profile.
browser:run	Mark a profile open or closed, without the right to edit it.
proxies:read	The saved proxy list, without passwords.
proxies:write	Create, edit and delete a proxy.
flows:read	The list of saved automation flows.
logs:read	The action log, the open log and sign in addresses.

One list, and every right on it guards something

A right that can be granted but guards no route is worse than none: the person who granted it believes the door is open, and the script is told no.

What a refusal tells your script

Three problems get three different answers, and telling them apart is the difference between a fix and an hour of guessing.

The key is not known
A revoked key, a mistyped key and a key that was never ours all read the same way, and nothing about the account is confirmed.
401
The plan has run out
The key is real and its rights are intact. Payment is the only thing missing, and the answer says so rather than hinting.
402
The right was not ticked
The key is valid and the route wants a right it does not carry. Make a new key rather than hunting for another address.
403

Where a key stops being useful

A key is shown once, at the moment you create it. After that only a fingerprint of it and its first characters are kept, so a lost key is replaced rather than recovered.

Revoking takes effect on the next call, and the record of the key stays behind on purpose. Without it the log would name actions done by a key nobody can identify.

Closing a person closes their keys

When access is cut for someone, the keys they made stop answering with it. A key that outlives the account it belongs to is an open door with no owner.

Often confused with

The token on your own machine
The automation interface on your computer has one token for the whole of it, with no rights and no expiry. It opens browser windows, which a server key never does.
A session pass
A person signs in and gets a short lived pass carrying every right their role has. A key is narrower and lasts until you revoke it.
A one time code
The second factor proves a person is at the keyboard. A key exists precisely so that nobody has to be.

What this does not do

A server key opens no browser window. Starting a profile from code is the job of the interface on your own computer, and a key only marks the profile busy and writes the log.
A key cannot make another key or a webhook subscription. Both need a person signed in with a password, so a leaked read only key cannot widen itself.
A route that declares no right is closed to keys entirely. The recycle bin and the fingerprint preview are read by a person, not by a script.
A key is not a separate member of the team. It sees exactly what its owner sees, so a folder restriction set on that person applies to their key as well.

Check it

Every claim above points at a file you can open and a stand that runs.

The key is stored as a fingerprint and handed over once: apps/server/src/api-keys/api-keys.service.ts · apps/server/test/api-keys.js
Every right on the list guards a real route, and keys belong to the paid plans: apps/server/src/api-keys/scopes.ts · apps/server/test/права-ключей-живые.js · apps/server/test/ключи-платные.js
Unknown key, spent plan and missing right are three different answers: apps/server/src/auth/api-key.guard.ts
The account screen shows the secret once and never again: apps/web/test/api-keys-web.js

Questions

How many keys can I hold at once?: Twenty live ones, and revoked keys do not count against that. The ceiling is there because a forgotten key is a door nobody remembers opening.
What happens when my subscription ends?: The key stops working and the answer names payment as the reason. The plan behind a key is checked as the key is used, not only on the day it was created.
Can I limit a key to a single profile?: No. Rights are chosen by kind of object rather than by object, so the narrowest key is one that reads and changes nothing.
Do you store the key itself?: No. A fingerprint of it is kept for matching and the first few characters for telling your keys apart, which is what the list shows you.
How do I see what a key did?: Each entry in the action log records the key that made it. That is what lets you revoke one contractor's key without stopping the rest of your automation.

Next to this

See the rights before you make a key

The account lists every right a key can carry and names what each one opens, so the narrow key is the easy one to make.

Download ARMANOS The API in full