# Keys and credentials

> Every credential form InfraInbox issues, where it goes, and how to rotate or revoke one.

Web page: https://infrainbox.app/docs/reference/keys/

Every credential is shown exactly once, at the moment it's created or rotated. InfraInbox stores only its hash; if you lose one, rotate it rather than trying to recover it.

## Credential forms

| Prefix | What it is | Where it goes |
|---|---|---|
| `iik_src_…` | A source's ingest key: creates events for that one source only. | `Authorization: Bearer iik_src_…` header, on `POST /v1/events` and on a tool's own webhook path. |
| `iik_hb_…` | A heartbeat monitor's ping-only token. | Either `Authorization: Bearer iik_hb_…`, or the token itself as the path segment of a cron-friendly ping URL. |
| `whsec_…` | A webhook destination's signing secret (Standard Webhooks–compatible). | Not sent by you — InfraInbox uses it to sign the `webhook-signature` header of what *it* sends to your endpoint. |
| A Gotify-style token (`A` and 14 more characters) | A Gotify-compatible source's alias token, for tools that only speak Gotify's legacy format. | `X-Gotify-Key` header, `Authorization: Bearer <token>`, or `?token=` on the query string if the source allows it. |
| An opaque token (no prefix) | A signed-in session or a paired device's access/refresh token. You never type these in — the dashboard and the app hold them for you. | A `Set-Cookie` session cookie (web), or `Authorization: Bearer <token>` (a paired app). |

> **Note:** Personal access tokens (`iik_pat_…`) are reserved for a later release and aren't issued yet.

## Where they live in the dashboard

- ****Settings › Workspace › API keys** (dashboard screen `/settings/keys`)** (owner/admin) — every source's keys in one place, grouped by source.
- **A source's own page**, Credentials tab — the same list, scoped to that one source.
- **A destination's edit page** — a webhook destination's signing secret, and a Telegram/Slack/Discord destination's bot token or webhook URL (shown as a hint once saved, never re-displayed in full).

## Shown once

A key or secret is displayed in full exactly once: right after you mint or rotate it. After that, only a hint (its last few characters) is shown. Copy it somewhere safe immediately — there's no "reveal" button later.

## Rotate

Rotating a source's key issues a new one immediately and keeps the **old one working for 24 hours**, so you have time to update the sender (Proxmox, a script, a crontab entry) before the old key stops working. Use this if a key may have leaked, or you're not sure whether it did.

## Revoke

Revoking a key stops it working immediately, with no grace period. Use this once you're certain a key is compromised, or a source no longer exists.

## URL forms that carry a secret

As a rule, InfraInbox avoids putting secrets in URLs — they end up in browser history, shell history and access logs. There are two deliberate exceptions:

- The **heartbeat ping URL**, `https://infrainbox.example.com/v1/heartbeats/iik_hb_…` — built specifically so a `curl` line in a crontab needs nothing but the URL. The server logs only the route pattern, never the actual path, so the token doesn't end up in its own logs.
- The **Gotify-compatible `?token=`** form, only when a source explicitly enables it, for senders that only support Gotify's query-parameter style.

Every other credential goes in a header.