All articles
Teams & Cloud
Secrets or Integrations: Which One to Use
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.