Skip to content
Point of Contact

Admin key

The admin key gates the dashboard and admin-only endpoints on your customer-stack Function App. It’s a single shared secret — anyone with it has full read+write access to your stack’s admin surface.

Bootstrap: your deployment starts with NO key

A fresh Managed Application deploy has no admin key: the gate runs in anonymous mode and every “admin-key gated” endpoint below is open to anyone who knows your Function App hostname (which becomes public as soon as the widget script tag is on your website). Your first post-install action is to mint the key:

  1. Open https://{customer-fa-host}/api/dashboard.
  2. Click Rotate admin key in the Settings panel.
  3. Save the key it shows — it’s displayed once.

That first rotation writes the key into your Key Vault and switches the gate on.

What it gates

  • GET /api/dashboard — the HTML admin dashboard
  • GET /api/cost, /api/sessions, /api/sessions/{id}/transcript — admin-only data endpoints
  • POST /api/ops/rotate-key — the rotate endpoint itself
  • GET /api/teams-app.zip, /api/teams-setup — Teams app generator

What it does NOT gate:

  • GET /api/plan — anonymous (used by the dashboard JS + future docs site)
  • GET /api/health — anonymous (deploy probe)
  • POST /api/chat, /api/chat/stream — visitor chat (anonymous; browser access limited by the CORS allowlist, plus rate limiting)
  • POST /api/agent/* — agent endpoints use the customer’s own AAD app for SSO

How to use it

Two ways to authenticate:

  1. Query string — ?code=<key> appended to the URL. The dashboard JS uses this when you first arrive with ?code= in the URL, then drops it on subsequent navigations (cookies take over).

  2. Authorization header — Authorization: Bearer <key>. Used by API integrations.

  3. Httponly session cookie — set automatically when you log in with a key. Survives until you sign out or rotate the key.

Where it’s stored

  • Customer Key Vault as the secret admin-key — the canonical copy, created on your first rotation and rotated in-place afterwards.
  • Function App env var ADMIN_KEY — a legacy fallback used only when the KV read fails. Marketplace deploys leave it empty (which is why a fresh deploy starts in anonymous mode).

The customer-runtime reads from KV first (short cache), falling back to env. We (the publisher) hold no copy and no Key Vault data-plane access.

How to rotate

The dashboard has a Rotate admin key button (admin-only). Clicking it:

  1. Generates a new 48-character hex value.
  2. Writes it to KV as the new admin-key secret value.
  3. Shows the new key once on screen for you to save.
  4. Invalidates all existing sessions (cookies signed with the old key fail signature check).

You’ll need to re-log-in with the new key. Old ?code= links die immediately.

Recovering a lost key

Two situations:

  1. You still have a signed-in dashboard session (the cookie survives until you sign out or rotate) — just click Rotate admin key and save the new value. Rotation only needs the current session, not the key itself.
  2. No session, no key — there is no self-service read path. The Managed RG’s deny assignment means nobody in your tenant can read the Key Vault secret or grant themselves a Key Vault role (az role assignment create inside the Managed RG is denied), and our publisher Contributor access can’t read your Key Vault either. Contact support — we verify your identity as the Marketplace purchaser and restore access through the publisher channel.

The practical takeaway: save the key to a password manager at first rotation, and treat rotation (case 1) as your recovery path.