Marginalia <mv-marginalia>

node scripts/add.mjs marginalia --out ./src/marvelous

<mv-marginalia>
  <p>Rotate API keys every 90 days<span data-note>NIST SP 800-57 allows up to two years; shorter limits the damage of a leak.</span>, then revoke the old key once traffic has moved.</p>
</mv-marginalia>

<div id="mg-demo" style="width:min(100%,64rem);margin-inline:auto">
  <style>
    #mg-demo { display:grid; gap:1rem }
    #mg-demo .mg-bar { display:flex; align-items:center; gap:.75rem 1.5rem; flex-wrap:wrap; padding:.75rem 1rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl); background:var(--mv-surface); box-shadow:var(--mv-shadow-xs) }
    #mg-demo .mg-width { display:flex; align-items:center; gap:.75rem; flex:1 1 20rem; min-width:0 }
    #mg-demo .mg-width label { font-size:.8125rem; font-weight:500; white-space:nowrap }
    #mg-demo .mg-width input { flex:1; min-width:6rem }
    #mg-demo .mg-width output { min-width:3.75rem; color:var(--mv-fg-muted); font-size:.75rem; font-variant-numeric:tabular-nums; text-align:end }
    #mg-demo .mg-status { display:flex; align-items:center; gap:.5rem; flex-wrap:wrap }
    #mg-demo .mg-stage { display:flex; justify-content:center; min-width:0 }
    #mg-demo .mg-doc { width:var(--mg-w,100%); max-width:100%; box-sizing:border-box; padding:2rem clamp(1rem,4vw,2.5rem) 2.25rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl); background:var(--mv-surface); box-shadow:var(--mv-shadow-sm); transition:width var(--mv-duration-normal) var(--mv-ease-out) }
    #mg-demo .mg-crumbs { margin:0 0 .5rem; color:var(--mv-fg-subtle); font-size:.75rem; letter-spacing:.02em }
    #mg-demo mv-marginalia { color:var(--mv-fg); font-size:.9375rem; line-height:1.7; --mv-marginalia-measure:39rem; --mv-marginalia-measure-min:26rem; --mv-marginalia-width:17rem }
    #mg-demo mv-marginalia h2 { margin:0 0 .375rem; font-size:1.5rem; line-height:1.25; letter-spacing:-.02em }
    #mg-demo mv-marginalia h3 { margin:1.75rem 0 .5rem; font-size:1.0625rem; letter-spacing:-.01em }
    #mg-demo mv-marginalia p { margin:0 0 1rem }
    #mg-demo mv-marginalia .mg-meta { margin:0 0 1.5rem; color:var(--mv-fg-muted); font-size:.8125rem }
    #mg-demo mv-marginalia code { padding:.05em .3em; border-radius:var(--mv-radius-xs); background:var(--mv-bg-muted); font:.86em var(--mv-font-mono) }
    #mg-demo mv-marginalia ol.mg-steps { margin:0 0 1rem; padding-inline-start:1.25rem }
    #mg-demo mv-marginalia ol.mg-steps li { margin-bottom:.375rem }
    #mg-demo mv-marginalia pre { margin:0 0 1.25rem; padding:.875rem 1rem; overflow:auto; border:1px solid var(--mv-border); border-radius:var(--mv-radius-lg); background:var(--mv-bg-subtle); font:.8125rem/1.6 var(--mv-font-mono) }
    #mg-demo mv-marginalia pre code { padding:0; background:none; font:inherit }
    #mg-demo mv-marginalia section[data-footnotes] { margin-top:1.5rem; padding-top:.75rem; border-top:1px solid var(--mv-border); font-size:.8125rem; color:var(--mv-fg-muted) }
    #mg-demo .mg-hint { margin:0; color:var(--mv-fg-muted); font-size:.75rem; text-align:center }
  </style>

  <div class="mg-bar">
    <div class="mg-width">
      <label for="mg-range">Reading width</label>
      <input type="range" class="mv-slider" id="mg-range" min="340" max="1024" step="4" value="1024">
      <output id="mg-out" for="mg-range">Full</output>
    </div>
    <div class="mg-status">
      <mv-segmented id="mg-mode" label="Note placement" value="auto">
        <button value="auto">Auto</button>
        <button value="inline">Inline only</button>
      </mv-segmented>
      <span class="mv-badge" data-variant="secondary" data-shape="pill" id="mg-count">-</span>
    </div>
  </div>

  <div class="mg-stage">
    <article class="mg-doc" id="mg-doc" aria-labelledby="mg-title">
      <p class="mg-crumbs">Docs / Security / API keys</p>
      <mv-marginalia id="mg-notes">
        <h2 id="mg-title">Rotating API keys without downtime</h2>
        <p class="mg-meta">Updated September 18, 2026 · 6 min read</p>

        <p>Every API key in your workspace is a long-lived secret. Rotating keys on a schedule limits the damage a leaked key can do<span data-note data-note-kind="source">NIST SP 800-57 Part 1, Rev. 5, §5.3 recommends cryptoperiods of one to two years for authentication keys.</span>, and most compliance programs ask for it. Scope each key to one service so a rotation never touches more than it has to, following the principle of <span data-note-anchor>least privilege</span><span data-note>A key used by billing should not be able to read customer files. Scopes are set once, at creation.</span>.</p>

        <h3>How rotation works</h3>
        <p>Rotation is a two-key handover. You create a successor key, deploy it everywhere the current key is used, then revoke the old key once traffic has moved over. During the overlap both keys authenticate normally<span data-note>The overlap exists so you never have to deploy every service at the same instant. Both keys share the same scopes, rate limits and audit trail, and each request records which of the two signed it, so you can see migration progress in the key's Activity tab. Keys created before March 2024 use the legacy <code>nk_</code> prefix: they rotate the same way, but their successor gets the current <code>sk_live_</code> format, so check any code that validates keys by prefix. If you use infrastructure as code, create the successor in the same change that updates the secret reference, and keep the old key out of the plan until traffic has drained; Terraform and Pulumi providers both expose a <code>rotation_window</code> argument for this. When the overlap ends before you revoke, the old key keeps working: nothing expires on its own, which is why the audit log flags keys that have been in rotation for more than 30 days.</span>, so no request fails while you roll out.</p>

        <ol class="mg-steps">
          <li>Create the successor key from <strong>Settings → API keys → Rotate</strong>.</li>
          <li>Update the secret in every environment, starting with staging.</li>
          <li>Watch the old key's traffic drop to zero, then revoke it.</li>
        </ol>
        <aside data-note data-note-kind="warning">Revoking is immediate and cannot be undone. Requests still signed with the old key fail with <code>401 Unauthorized</code>.</aside>

        <pre data-note-wide><code>curl -X POST https://api.northwind.test/v2/keys/key_7Hq2/rotate \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d overlap=72h -d [email protected]</code></pre>

        <h3>Choosing an overlap window</h3>
        <p>A 72-hour overlap covers weekly deploy trains and most mobile release cycles<span data-note>Mobile apps are the slow path: a key baked into a build lives as long as users keep that version installed. Ship keys to mobile clients through your backend instead, so rotating one never waits on an app store review, and old app versions keep working without a forced update. If you must embed a key, give it read-only scopes and rotate it with every major release.</span>. Long-running batch jobs are the usual exception: a nightly export that starts with the old key keeps using it until it finishes<span data-note data-note-kind="source">Measured across 1,240 workspaces in Q2 2026: the median export job runs for 41 minutes, the 99th percentile for 7.5 hours.</span>, so revoke after the last run that began inside the window.</p>
        <p>Teams on the Enterprise plan can schedule rotations and get a chat or email reminder before each one<sup><a href="#mg-fn-1" id="mg-fnref-1" data-footnote-ref>1</a></sup>. Scheduled rotations use the same overlap window as manual ones.</p>

        <section data-footnotes class="footnotes" aria-label="Footnotes">
          <ol>
            <li id="mg-fn-1"><p>Reminders go to workspace owners and to anyone subscribed to the <em>security</em> channel, 7 days and 24 hours ahead. <a href="#mg-fnref-1" data-footnote-backref aria-label="Back to reference 1">↩</a></p></li>
          </ol>
        </section>
      </mv-marginalia>
    </article>
  </div>
  <p class="mg-hint">Narrow the page: long notes leave the margin first and become numbered toggles under their line · Hover a note or its number to link them</p>

  <script type="module">
    const notes = document.getElementById("mg-notes");
    const doc = document.getElementById("mg-doc");
    const range = document.getElementById("mg-range");
    const out = document.getElementById("mg-out");
    const count = document.getElementById("mg-count");
    const mode = document.getElementById("mg-mode");

    const fit = () => {
      const max = Math.floor(doc.parentElement.clientWidth);
      range.max = String(Math.max(360, max));
      const full = Number(range.value) >= Number(range.max);
      doc.style.setProperty("--mg-w", full ? "100%" : `${range.value}px`);
      out.textContent = full ? "Full" : `${range.value} px`;
    };
    range.addEventListener("input", fit);
    new ResizeObserver(fit).observe(doc.parentElement);
    fit();

    mode.addEventListener("mv-change", (e) => { notes.mode = e.detail.value; });

    const paint = () => {
      const list = notes.notes;
      if (!list.length) return;
      const m = list.filter((n) => n.mode === "margin").length;
      count.textContent = notes.layout === "margin" ? `${m} in the margin · ${list.length - m} inline` : `All ${list.length} inline`;
      count.dataset.variant = notes.layout === "margin" ? "info" : "secondary";
    };
    notes.addEventListener("mv-layout", paint);
    await customElements.whenDefined("mv-marginalia");
    requestAnimationFrame(paint);
  </script>
</div>