> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpalive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up HelpAlive: four steps, project key and signing secret

> Follow HelpAlive's four setup steps, check that each one works, and manage your public project key and your private signing secret.

**Setup & API Key** is the page in the HelpAlive dashboard where you install HelpAlive and check that it works. It is the second tab of **Settings**, at **Settings → Setup & API Key**. It also holds your project key and your signing secret.

## Setup at a glance

* Setup has four steps: **Add HelpAlive to your app**, **Train the agent on your product**, **Test it on your app** and **Verify your users**, which is optional.
* Each step has one line saying what HelpAlive saw, and gets a check by itself once it is done.
* **Your project key** is public: it goes in the script tag on every page.
* Your signing secret is private. Keep it on your server, like a password.
* With **Only allow verified users** on, anyone without a valid user token can't see the agent.

## Is it working?

The band at the top says how many of the 4 steps are done and what to do next, in one sentence. Once the first three are done, it says your agent is ready for your users. When everything works, **Everything is working.** shows beside the refresh button.

Each step in the list on the left has one line saying what HelpAlive saw:

| Step | Its line when it is done |
| - | - |
| **Add HelpAlive to your app** | "Recognized a signed-in person 3 minutes ago." Before that, "On your pages. Waiting for someone to sign in to your app." |
| **Train the agent on your product** | "2 sources live for the agent." |
| **Test it on your app** | "Tested in your app: ..." once a test link ran an assist or a chat. |
| **Verify your users** (optional) | How many sign-ins in the last 7 days arrived verified. |

The checks need a real visit: once the tag is live, sign in to your app, click around, and come back to this page. It checks again when you return, so you don't need to refresh.

The sidebar's **Setup** checklist counts the same 4 steps, by shorter names: **Add HelpAlive**, **Train the agent**, **Test it on your app** and **Verify users**. Done steps stay in it with a check.

## The four steps

The steps are listed on the left, one shown at a time. Each gets a check by itself once it is done.

1. **Add HelpAlive to your app**: your developer, about 10 minutes. Choose **With an AI coding agent**, **Add it yourself** or **Google Tag Manager**. The first gives a prompt to paste into your coding tool; the second, the tag, `identify()` and `reset()`. Under **Tell HelpAlive who is signed in**, pick **B2B: users belong to tenants** or **B2C: users have no tenant**. See [Install the script](/installation) and [Identify users](/sdk/identify).
2. **Train the agent on your product**: add your docs on **Train** and publish them. See [Train](/dashboard/train).
3. **Test it on your app**: "Try the agent in your own app, in your browser only. The Test page shows you how." The button opens the dashboard's **Test** page. The step turns green once a test has run an assist or a chat. This step is locked until a source is published. See [Test it on your app](/dashboard/test#test-it-on-your-app).
4. **Verify your users**: optional, recommended. See [Verified users](#verified-users).

## Your project key

**Your project key** sits under the steps. It is public: it goes in the script tag on every page, and the code on this page already contains it. **Copy** copies it.

**Regenerate** makes a new key, so update your script straight away. If your pages used the key in the last week, the dialog warns you first. You can regenerate once an hour.

## Verified users

Without this step, HelpAlive trusts the user id your page sends. This means that someone who edits the page in their browser could send another person's id and read that person's chats. With it, your server signs each id, and once **Only allow verified users** is on, nobody can pretend to be someone else. Add it before you open the agent to all your users.

### Your signing secret

Press **Create your signing secret**. Keep it on your server, like a password. The code samples read it from `HELPALIVE_SIGNING_SECRET`; the name is up to you. **Reveal** shows it and **Copy** copies it.

<Warning>
  The signing secret is private. Never put it in your page, your app's front-end code or a prompt to an AI tool.
</Warning>

**Rotate** issues a new secret. Put it on your server; nothing in your code changes. The previous secret keeps working until you rotate again, so nobody is refused while you roll it out. If a secret leaked, rotate once more after your server uses the new one, and the leaked one stops working.

### Make a user token

Under **Make a user token on your server, and pass it to identify()**, choose **With an AI coding agent** or **Add it yourself**. The code comes in eight server languages. The user token refers to a short signed text your server makes per person. Your page passes it to `identify()`. The code is on [Verify users](/sdk/verify-users).

### Check your setup

After you deploy your signing, sign in to your app and open the agent. Then press refresh under **Check your setup**: it looks for a verified sign-in in the last 30 minutes.

**Verified sign-ins, last 7 days** shows what share of sign-ins arrived verified, unsigned or failed.

### Only allow verified users

With this switch on, anyone without a valid user token can't see the agent, and their activity is not recorded.

* It can be turned on only after a verified sign-in in the last 30 minutes. **Recommended** means that nearly all sign-ins in the last 7 days arrived verified and none failed.
* Turning it on asks first, and says how many people in the last 7 days would lose the agent.
* Turning it off always works, so you have a way out if signing breaks.

While the switch hides the agent from some people, step 4 says how many, the main reason and the fix, and we email your team. See [Verify users](/sdk/verify-users).

## Check it works

The first three steps have a check, and the band says your agent is ready for your users.

## Troubleshooting

* **"Our script reaches your pages but can't start."** This means that the tag has the wrong project key. Copy it again from this page.
* **"Last seen on your pages ... Is the tag still there?"** This means that the tag was removed, or your pages stopped loading it.
* **Step 1 stays on "Waiting for someone to sign in".** This means that `identify()` isn't running. Call it after login and on every page load.
* **Some users can't see the agent after you turn on Only allow verified users.** This is because their pages send no token, or a token that fails. Step 4 names the main reason and the fix. Turn the switch off while you fix the signing, then turn it on again.
* **"Too soon to regenerate."** This is because the project key can be regenerated once an hour.

## Next

<CardGroup cols={3}>
  <Card title="Install the script" icon="code" href="/installation">
    The tag and `identify()`, step by step.
  </Card>

  <Card title="Verify users" icon="shield-check" href="/sdk/verify-users">
    Server code in eight languages.
  </Card>

  <Card title="Controls" icon="sliders" href="/dashboard/controls">
    Turn the agent on.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.