ik_live_…) is the credential for a server. An endpoint URL is what you paste into a provider’s dashboard; a key is what your own code sends with, and it is the only way to use three things:
- Rules.
POST /v1/ingest/{key}with no dataset in the path runs the project’s mapping rules, and stores an event none of them matches in the key’s default dataset. - The live stream.
GET /v1/streamauthenticates with a key and tails that key’s project. See Live streaming. - Hookie’s own inbound signature. A key can require every request to carry an
X-Hookie-Signature(t=<unix>,v1=<hex>, an HMAC-SHA256 over<t>.<body>with the key’s signing secret). See request headers. To check a provider’s signature (Stripe, GitHub and others), use endpoint signature verification instead.
Create a key
1
Open the Ingest keys tab
In the console, open the project and choose Ingest keys. Owners, admins and developers can create and change keys; viewers see the list.
2
Create it
Choose Create key and give it the name of the sender that will use it. Optionally set:
- a default dataset, where an event sent with no dataset in the URL is stored, as one record holding the whole payload, when none of the project’s rules matches it. Leave it empty to use
default; - an expiry, after which the key is refused exactly as if it had been revoked;
- allowed source IPs, one IP or CIDR range per line;
- require a signature, which also mints a signing secret.
3
Copy it now
The key (and its signing secret, if any) is shown once. Hookie stores only a SHA-256 hash of the key and its first 16 characters, which is what the list shows from then on.
default unless you choose one when you create the key). When you send to POST /v1/ingest/{key} without a dataset in the URL, the project’s rules route the event. If none of them matches, Hookie stores the whole payload as one record in the key’s default dataset rather than dropping it. That record is delivered, streamed and handed to AI triggers and workflows like any other, and the request counts as one event, the same as a rule-routed one. The response tells you which happened: fallback: true with routed: ["<default dataset>"] when the default dataset caught it, and fallback: false with the names of the matching rules otherwise. Naming a dataset in the URL (/v1/ingest/{key}/{dataset}) writes straight to it and never uses the default. Endpoint URLs always write to the endpoint’s own dataset. The default dataset is fixed when the key is created and is carried over when you rotate it.
The list shows each key’s name, prefix, status, expiry, allowed IPs, default dataset, when it was last used and when it was created. Status is active, rotating (still working, with a replacement and a deadline), expired or revoked. Only an active or rotating key authenticates.
Restrict a key to your servers
A key’s allowed source IPs refuse every request from anywhere else with403 Source IP not allowed, and each refusal is recorded in the audit log as ingest_ip_blocked. Entries are IPv4 or IPv6 addresses or CIDR ranges, up to 64, validated the same way as the project and workspace allowlists. An empty list accepts any address.
The lists stack: a request must pass every one that is set, whether on the key (or the endpoint), the project or the workspace. A key’s list can only narrow what the project and workspace allow.
Set it when you create the key, or later with Edit… on the key’s row. The same field is on an endpoint’s Edit… dialog, for endpoint URLs.
Rotate without an outage
Rotate… issues a new key with the same name, default dataset, allowed IPs and signature requirement, and gives the old key a deadline. Until then both work, so you can move every sender over, then let the old one lapse.1
Rotate
Choose how long the old key keeps working: an hour, a day (the default), a week or 30 days. End it now stops it at once, which breaks anything still using it.
2
Copy the new key
It is shown once, like a new key. A key that requires signatures gets a new signing secret too, so a rotation after a leak does not carry the leaked secret forward.
3
Update your senders
The old key’s row reads rotating until its deadline and expired after it. To give yourself more time, use Edit… on the old key and move its expiry.
Revoke
Revoke… stops a key on its very next request, at ingest and on/v1/stream. It is not reversible, and the row stays listed with its history. To replace a key without an outage, rotate it instead.
Endpoint URLs rotate too
An endpoint’s URL is its credential in the same way. On the Endpoints tab, Rotate URL… gives the endpoint a new URL while keeping the same endpoint: its id, dataset, settings and records are unchanged. The old URL keeps working through the overlap you choose (a day by default), and the card says until when. Edit… renames an endpoint, points it at another dataset from now on, and sets its allowed source IPs.From the API, an agent or the CLI
expires_at is an ISO 8601 time in the future, or null for never. ip_allowlist is an array; [] or null removes it. Every change is recorded in the audit log, and neither a key nor an endpoint URL ever appears in it.