Ping keys

A project ping key lets your jobs ping checks by name instead of by token. You put one key in your scripts, and give each check a slug such as backup-db-nightly.

Ping keys compared to ping URLsCopy Anchor Link

Both are secrets, but a leaked ping key reaches further. Anyone who has a project's ping key can ping every check with a slug in that project. A check's ping URL only reaches that one check. Neither credential can read your data or change project settings.

The URLCopy Anchor Link

https://api.flatlyne.com/<ping-key>/<slug>

Every ping form works with a ping key:

These behave exactly like the token forms, including the 3-pings-per-minute limit for each check. See Ping URLs for what each one records and returns.

PING_URL=https://api.flatlyne.com/RudYgUFqrxce2CdpAHz3csYP83ml_HKdSoBwxeezF_o/backup-db-nightly
0 2 * * * /usr/local/bin/backup-db-nightly.sh; curl -fsS -m 10 --retry 5 "$PING_URL/$?"

The first line sets PING_URL, a variable cron passes to the command.

Slug rulesCopy Anchor Link

A slug is the last path segment that names the check, such as backup-db-nightly or sync_invoices. FlatLyne matches it exactly against the slugs of checks in the key's project.

• Use 1 to 100 lowercase letters, digits, - or _. Nothing else is allowed: no spaces, uppercase letters or other characters.
• start and fail can't be slugs, because /<ping-key>/start and /<ping-key>/fail are read as start and fail pings.
• Each slug belongs to only one check in a project.

A ping to a slug that no check in the project has gets 404, and nothing is recorded. Set the slug on the check first.

Set or change a slug in the dashboardCopy Anchor Link

A ping key only reaches a check that has a slug. To set one:

• When you create a check, fill in the optional Slug field.
• For an existing check, select its name, in your checks list or at the top of the check's page, to open Edit name and slug. On the check's page, Add a slug under Slug URL opens the same dialog.

The slug must follow the slug rules.

You can change a slug, but you can't remove it. After you change it, the old slug no longer points to this check, so a job that still pings the old slug gets 404. Update your jobs first.

In the checks list, switch the URL column from Ping URL to Slug URL to see each check's ping key URL. FlatLyne stores only a hash of each ping key, so the URL shows <ping-key> in place of the key. Copy it and replace <ping-key> with a key from Settings → Ping keys. The check's page shows the same URL under Slug URL.

Create a ping keyCopy Anchor Link

You need a role that can edit the project. Read-only members can see the list of keys, but can't create or revoke them.

The Ping keys page lists every key that hasn't been revoked, with its label, the first characters of the key, when it was created and when it expires. A key past its expiry date shows Expired.

A project can have several active ping keys at once, so you can give each server or team its own key.

Revoke or rotate a ping keyCopy Anchor Link

To revoke a key, go to Settings → Ping keys, select Revoke on its row and confirm. From then on, every ping that uses it gets 404. Your checks stay, with their history. A key with an expiry date stops working the same way once that day ends.

To rotate a key without missing pings:

1. On Settings → Ping keys, create a new key.
2. Update your jobs to use the new key.
3. Revoke the old key.

Checks belong to the project and are matched by slug, not by key, so the same checks keep their history after you switch keys.

What's nextCopy Anchor Link

• Look up every ping URL and response
• Report failures and exit codes
• Adjust a check's schedule
• Copy a ready-made snippet