API keys

This page explains how to create, view, replace and revoke the API key that lets your own scripts and tools use the EyalSec API without signing in through the website.

What an API key is

An API key is a secret that lets a program call the EyalSec API as you. With a full-access key it can do what you can do on the dashboard: read events, manage machines, filters, rules and source settings. Treat it like a password.

You can have one key at a time, and you manage it on the API access page of Settings. What you can call with it is in the API overview and on the API page in the dashboard sidebar.

Generate a key

Generating a key creates a new secret and shows it to you once. The box is called Generate a key (with no key beside it) when you have none, and Regenerate key when you already have one.

1. Open Settings > API access and go to Generate a key.
2. Optionally set an Expiry date (see Expiry).
3. Optionally tick Read-only (see Read-only keys).
4. Enter your password under Confirm password, and a 2FA code if the field is shown.
5. Click Generate API key.

The key appears in a box that says "Copy your API key now; it won't be shown again." It starts with es2_ followed by a long random string, like this made-up example:

es2_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0000

Copy it straight away. EyalSec keeps only a scrambled form of it and cannot show it again; if you lose it, generate a new one.

Expiry

Expiry is an optional date after which the key stops working. Leave it empty for a key that does not expire.

The date must be in the future, or the page says "Expiry must be a valid future date (YYYY-MM-DD)." The key stops working at the start of that day (UTC). A request with an expired key gets 401 with invalid or expired API key.

Read-only keys

A read-only key can read your data but never change it. Tick Read-only (GET only (no writes)) when you generate the key; a key without it has full access.

Read-only is decided per API endpoint, not only by HTTP method, so the events search (which is sent as a POST) still works with a read-only key. Any request that would change something is refused with 403 and this API key is read-only. Use a read-only key for dashboards, exports and anything else that only looks.

View your key

Once a key exists, the Active key box shows its details, never the full secret. Its title line shows the key's first characters (for example es2_EXAM…) and whether it is read-only or full access.

Below that you see when the key was created, when it expires, when it was last used and from which IP address, and a sample command. Use these details to spot a key being used from somewhere you do not expect.

Regenerate a key

Regenerating replaces your key with a brand-new one, shown once. The old key stops working immediately, so update everything that used it.

Under Regenerate key, optionally set a New expiry and Read-only, confirm with your password (and 2FA code), and click Regenerate. The new key does not inherit the old key's expiry or read-only setting; set them again.

Revoke a key

Revoking deletes your key, so nothing can use it, until you generate a new one. Do it when you no longer need API access or think the key has leaked.

Under Revoke key, enter your password under Confirm password to revoke, and click Revoke. The page says "API key revoked."

Changing your password also revokes the key automatically. See Change your password.

Use the key

Send the key in a request header named X-API-Key. Every API path is under your EyalSec address; the example below lists your machines.

curl -H "X-API-Key: es2_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0000" \
  https://eyalsec.com/api/get_all_machines/

A key is limited to about 5 requests a second, with short bursts allowed; past that you get 429 and should wait a second. See Authentication and Rate limits for the details, and keep the key out of source control and shared logs.