Skip to main content

Poweruser Keys

A poweruser key is a personal credential that lets scripts and integrations act as you against the Poweruser API — creating agents, editing tools, managing tables, and everything else your account can do in the builder. Each user holds at most one active permanent key, plus on-demand temporary keys that expire after 15 minutes.

What it's for​

Client API keys execute what you've published; poweruser keys manage the workspace itself. Reach for one when you're automating administration: provisioning resources from CI, running migrations, syncing configuration, or wiring back-office scripts. Because a poweruser key inherits your full permissions, treat it like your password — it belongs in a secrets vault, never in client-side code or version control.

Open API Management → Poweruser Keys in the sidebar. If you have no key yet, the page offers Generate Poweruser Key and Generate Temporary Key (15 min). Once a permanent key exists, an Active Poweruser Key card shows its name, truncated key ID, and an Enabled/Disabled status, with Generate Temporary Key (15 min), Rotate Key, and Revoke Key actions.

Key concepts​

  • Acts as you. Every call authenticated with the key runs with your identity — the same resources, roles, and company scope you have in the builder. There is no narrower resource picker on this page; the key covers everything you can touch.
  • Permanent keys have the shape pwrusr:{id}:{secret} and are passed in the Authorization header. The full value is displayed exactly once, masked behind a Show/Hide toggle with a Copy Key button; after you click I've Saved My Key - Continue it cannot be retrieved again.
  • One active permanent key. You can hold only one permanent key at a time (per company) — the backend refuses to mint a second, and the UI replaces the Generate button with Rotate/Revoke once a key exists. To change the secret, rotate; to start over, revoke first.
  • Temporary keys have the shape pwrusr_temp:{jwt} and expire 15 minutes after issue — the lifetime is fixed, with no options. They behave identically to permanent keys while valid, don't count against the one-key rule, and are ideal for one-off jobs or handing a short-lived credential to a support session. Generate as many as you need.
  • Endpoint scoping is for delegated credentials, not this page. Keys generated here are full-scope. When poweruser access is delegated to something you don't fully control — for example a hosted custom app calling admin endpoints on the owner's behalf — the credential is scoped to an explicit list of allowed poweruser endpoints instead. You configure that in the app's settings, not here.

How to generate and use a key​

  1. On the Poweruser Keys page, click Generate Poweruser Key (or Generate Temporary Key (15 min) for a short-lived credential).
  2. Copy the key from the success modal — heed the warning: "This is the only time you'll see this key."
  3. Store it in a secrets manager and pass it in the Authorization header of Poweruser API calls. See the Poweruser API reference for the base URL and request shape.

How to rotate or revoke​

  1. Click Rotate Key to invalidate the current secret and get a new one — the confirmation modal requires ticking "I understand this will invalidate my current key". The key ID stays the same; every application using the old value stops working immediately, so update them with the new secret from the copy-once modal.
  2. Click Revoke Key to kill the key outright (confirmation checkbox required, irreversible). The page returns to its empty state and you can generate a fresh key whenever you're ready.

Rotation is the right response to any suspected exposure — it takes effect immediately and the old secret can never be recovered or re-enabled.

The generation modal also lists the security basics worth repeating: keep the key in a password manager or secrets vault, never commit it to version control, don't share it over email or chat, and rotate periodically.