Knowledge Hub

The HQ Knowledge Hub

Plain-English guides to HQ, from your first install to rolling it out across your whole team.

On this page

Teams & Cloud

Secrets or Integrations: Which One to Use

2 min read Updated Nov 2026

Anyone deciding how to give HQ access to another tool.

  • An integration connects HQ to another app, like Linear or Notion. Once it's connected, HQ can read and update that app for you.
  • A secret is a password or API key saved safely in HQ. HQ can use it without anyone seeing it.

Use an integration when the app has one. Use a secret when it doesn't.

Use an integration#

To see if an app has one, ask HQ: "Can I connect Linear to HQ?"

Why it's the better choice:

  • It's connected once and shared with the people who need it. Nobody has to handle a key.
  • Changes wait for approval. By default, an owner approves changes before they happen.
  • Every use is recorded, so owners can see what was done.

How to connect one: Connecting Your Apps to HQ.

Use a secret#

Use a secret when:

  • The app doesn't have an integration HQ can use yet, and only gives you keys. Shopify is one example. See Connecting Shopify to HQ.
  • You're building an app that needs a password or key to run, like a database password.
  • A script needs a key, like one that pulls numbers from Stripe.

Keep in mind:

  • A secret has no approval step. Anyone you share it with can do whatever the key allows. Use read-only keys when you can.
  • Never paste a secret into a chat. The Secrets Guide shows how to save one safely.

Common questions#

An app asked for an API key when I connected it as an integration. Do I also save it as a secret?

No. HQ keeps the key with the integration.

I saved a key as a secret, but the app has an integration. Should I switch?

Yes. Connect the integration, then delete the secret if nothing else uses it.

Not sure which one you need?

Ask HQ: "Should I use a secret or an integration for this?" and name the tool.

If you get stuck#

See The "I'm Stuck" Guide, or report it with /hq-bug.