import { useEffect, useState } from "react"; import { api, type ApiToken } from "../api/client"; import CopyButton from "../components/CopyButton"; import { EmptyRow } from "../components/EmptyState"; import { ErrorNotice } from "../components/Notice"; import { BlockSkeleton } from "../components/Skeleton"; import TimeAgo from "../components/TimeAgo"; import { confirmDialog } from "../utils/dialogs"; import { formatDate } from "../utils/date"; import { readableError } from "../utils/errors"; import { toast } from "../utils/toast"; import PageIntro from "../components/PageIntro"; const EXPIRY = [ { value: "90", label: "90 days" }, { value: "30", label: "30 days" }, { value: "365", label: "1 year" }, { value: "", label: "No end — until I remove it" }, ]; const READS = [ ["/api/v1/servers", "every server: whether it is online, its addresses, load, memory, disks and waiting updates"], ["/api/v1/servers/:id/metrics?days=365", "a server's load, memory and disks, up to a year back"], ["/api/v1/alerts", "what is wrong now, and whether somebody is on it"], ["/api/v1/incidents?status=open", "the record of alerts that began and ended"], ["/api/v1/inventory", "the hardware"], ["/api/v1/network", "switches, access points and gateways, networks and Wi-Fi names"], ["/api/v1/endpoints", "the checks, and /endpoints/:id/history for how one has done"], ["/api/v1/maintenance", "what is under maintenance now, and what is coming"], ]; /** * A person's own read-only tokens for the API (/api/v1): a script, Home Assistant or a dashboard sends one in a header and gets JSON back. A token can only read, sees * what its owner sees, and is gone when its owner is. The secret is shown once, here, when it is made. */ export default function ApiTokens() { const [tokens, setTokens] = useState(null); const [max, setMax] = useState(10); const [error, setError] = useState(null); const [label, setLabel] = useState(""); const [expiry, setExpiry] = useState("90"); const [busy, setBusy] = useState(false); const [fresh, setFresh] = useState<{ label: string; secret: string } | null>(null); function load() { api.apiTokens .list() .then((res) => { setTokens(res.tokens); setMax(res.max); }) .catch((err) => setError(readableError(err))); } useEffect(load, []); async function make(e: React.FormEvent) { e.preventDefault(); setBusy(true); setError(null); try { const res = await api.apiTokens.create({ label: label.trim(), expiresInDays: expiry === "" ? null : Number(expiry) }); setFresh({ label: res.token.label, secret: res.secret }); setLabel(""); load(); } catch (err) { setError(readableError(err)); } finally { setBusy(false); } } async function remove(t: ApiToken) { // Not undoable: the secret is not kept, so a token cannot be made again the same. if (!(await confirmDialog({ title: "Remove a token", message: `Remove "${t.label}"? Whatever uses it stops working at once, and it cannot be put back.`, confirmLabel: "Remove", danger: true }))) return; try { await api.apiTokens.remove(t.id); toast.success(`Removed "${t.label}".`); load(); } catch (err) { toast.error(readableError(err)); } } const origin = window.location.origin; return ( <>

API tokens

Read-only access to your installation’s data for scripts, Home Assistant and dashboards. A token can only read, sees what you see, and stops working when you are removed. Make one for each thing that reads, so each can be removed on its own. {fresh && (
Your token “{fresh.label}” — copy it now, it is not shown again
{fresh.secret}
Send it in a header, never in the address:
{`curl -H "Authorization: Bearer ${fresh.secret}" ${origin}/api/v1/alerts`}
)}

Make a token

setLabel(e.target.value)} />
{(tokens?.length ?? 0) >= max &&
You have {max} tokens, the most there can be. Remove one you do not use.
}

Your tokens

{tokens === null && !error && ( )} {tokens?.map((t) => ( ))} {tokens !== null && tokens.length === 0 && }
Name Starts with Made Last used Ends Actions
{t.label} {t.expired && expired} {t.tokenPrefix}… {t.lastUsedAt ? : never} {t.expiresAt ? formatDate(new Date(t.expiresAt)) : no end}

What it can read

Everything is a GET that answers JSON, under {origin}/api/v1, with the token as Authorization: Bearer …. Nothing can be changed through it. Dates are ISO 8601 in UTC and sizes are in bytes.

    {READS.map(([path, what]) => (
  • {path} — {what}
  • ))}
The full list, with an example of each answer, is in docs/API.md.
); }