Access Keys

An access key opens the agent to another program — with no password and no login form. Each device or script can have its own key with a readable name: you can see who uses what, and revoking one key never disturbs the others. This page covers how to issue such a key, where it is stored, and what exactly it opens.

---

Why you need this

Before, access from programs was opened by a single key in the AGENT_API_KEY environment variable. That key was shared: to revoke one contractor’s access, or to change the key after a leak, you had to replace the only key and reconfigure everyone who used it.

Named keys solve this: create a separate key for every device, program, or contractor and give it a readable name. The list shows at a glance who uses what. Deleting or regenerating one key stops only that key — the rest keep working.

The keys live in a file inside the project, and together with the project it lands in version control. Only the salt and hashes are stored there — the keys themselves are never written to the file — so it is safe to keep and share.

Where to manage keys

Keys are created and edited in Settings → the Configuration group → the Access Keys card.

Changes save instantly: every action has its own separate result, and there is no Save button. You can close the dialog at any moment — nothing will be lost.

The key list

Each key occupies its own row in the list: the name and the first 12 characters of the hash on the left, three actions on the right.

• Rename — change the name without touching the key itself;
• Regenerate — issue a new key under the same name; the previous key stops working right away;
• Delete — revoke the key.

Deleting and regenerating ask for confirmation first and warn you plainly: the current key stops working immediately.

How to create a key

1. Press “Generate Key”.
2. In the “New Access Key” window, enter a name — 1 to 64 characters: letters, digits, underscore, or hyphen. Names must not repeat; case does not matter.
3. Confirm — the key appears in the list.

Right after creation, the key is shown once in a separate panel: the full key in a field with a copy button and the warning “Copy the key now — it will not be shown again.” Copy the key and hand it to whoever it was made for. Next to it there is a “Copy hash” button — handy when you need to check the entry in the file.

A key looks like agent_ plus 32 more random characters from latin letters and digits. The agent_ prefix helps you recognize the key when it sits next to other keys and tokens.

There is no way to view the key later: once the panel is closed, only its hash remains in the system. If a key is lost, issue a new one under the same name with “Regenerate”.

How to use a key

The key is sent in the X-API-Key header — exactly like a key from the environment variable:

X-API-Key: agent_your-key

Live connections (WebSocket/SignalR) cannot carry headers, so the same key is passed as an address parameter:

/svelteChatHub?api_key=agent_your-key

For commands, addresses, and request examples, see the API page.

What the key grants

A valid key grants full access: it opens every /api/* address and the live-events subscription to the caller with the manager role — the same access as signing in as the manager, and with no expiration.

A wrong key presented this way is rejected with a 401 Unauthorized error on any API address — even when a valid login token is passed alongside.

If you pass no key at all, nothing changes: the regular interface login keeps working. The agent’s own interface never sends the key — named keys are for external programs only.

Deleting and regenerating take effect immediately — no agent restart needed.

The keys.yml file

All named keys are stored in the keys.yml file in the project folder — .xedant/keys.yml:

salt: 9f1c...        # the salt — 64 hexadecimal characters, created once
keys:
  - name: laptop
    hash: a3b5c...   # SHA256(salt + key), 64 hexadecimal characters
  - name: ci-runner
    hash: 77d0e...

Every key is stored only as its SHA256(salt + key) hash. The salt is a random string shared by all the keys, created once when the file appears. The key itself is never saved anywhere and cannot be recovered from the file.

The file is created together with the first key — there is nothing to prepare in advance. It is safe to commit to a repository: only the salt and hashes are inside.

By hand, the file is edited in Settings → Project Settings → the keys.yml tab — for example, to add a key by computing its hash with the same formula.

If the file is edited in two places at once, the first edit wins: the second save is checked against the file’s fingerprint and rejected with a request to reload the list — so nobody’s change is silently overwritten.

Enabling the Remote API

The /api/remote addresses work when the AGENT_API_KEY variable is set or the file defines at least one named key. A single named key is enough to switch them on.

With neither in place, remote requests get a 503 Service Unavailable response explaining that an access key is needed.

For details, see the API and Remote Control pages.

Related sections

• API — commands, addresses, and key-based authorization;
• Login & Authorization — every way into the agent;
• .xedant Folder — where the project’s settings live, including keys.yml;
• Settings — the settings card center and the Access Keys card.

---