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 Actions, Profile sessions and IP log tabs.

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.

What revoking leaves behind

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.

The owner sees the keys of the whole team

Everyone sees only their own keys under API keys. The owner and the admins of a team also see Team API keys below it: every key issued in this team, including the keys of other people. Each key says whose it is, which rights it has, when it was issued, and when and from which address it was last used.

Any key of the team is revoked with Revoke in its line, after a question. A revoked key stops answering right away, and the log keeps an API key revoked record with who revoked it and the email of the person whose key it was. A server updated before this version does not show this section.

Often confused with

The access token on your own machine
The local API on your computer has one access 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 local API 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 group restriction set on that person applies to their key as well.
A key does not travel across its owner's teams. It works only in the workspace where it was issued, even when the owner belongs to several. When the owner leaves that workspace, the key stops working, and it can be revoked from the owner's own workspace.

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 dashboard shows the secret once and never again: apps/web/test/api-keys-web.js
A key of a workspace its owner left stops working and is revoked from the owner's own workspace: apps/server/src/api-keys/api-keys.service.ts · apps/server/test/несколько-команд.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 audit 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.

Sign-ups paused for now The local API in full