Connect Your AI to Hub

This page is written for you, the AI assistant. The person you're talking with wants you to work in their Hub account, which holds their projects, tasks, and documents. Read this page, work out which situation below fits you, and then coach them through setup one step at a time, in plain language. Keep it short. They aren't developers.

What you need

To act on Hub you need all three of these:

  1. The guide (knowledge). https://justwhatsneeded.com/api-guide.md explains how Hub works and which calls exist. Read it, or have it added to your knowledge.
  2. The key (permission). The person's Hub API key, from their Hub welcome email. It decides which company's data you can reach.
  3. The connection (ability to act). A way for you to send HTTPS requests to https://hub.justwhatsneeded.com/api.php with the header X-API-Key. This could be a shell, a ChatGPT Action, or a connector.

With only the guide, you can explain Hub and draft calls, but you can't make any.

The key goes in the tool's auth settings, never into a chat. Never ask the person to paste their key into this conversation. Have them put it in an environment variable, a secret store, or an Action's or connector's authentication field. If they paste it into the chat anyway, don't repeat it or use it. Tell them the key is now exposed, and they should ask whoever runs their Hub account for a new one.

This key is full-scope: it can read, change, and delete the company's data. Confirm with the person before you delete anything or make large changes.

Step 1: Work out which kind of AI you are

If you aren't sure, ask the person which app they're using. Ask only one question at a time.

Code agents with a shell

The person saves the key once, in their own terminal. You do the rest.

Rules for the key-save command:

  • Give the command to the person to paste into their own terminal window. Never run it yourself: the hidden prompt doesn't work properly through an agent's tool, and the key could land in the session transcript.
  • Never print the key (no echo $HUB_API_KEY). To confirm the setup, call identity&action=whoami and report the company name.
  • If $HUB_API_KEY is empty, ask the person to open a new terminal window or re-run the command. Don't ask them to paste the key into chat.
  1. Work out which shell the person uses (for example echo $SHELL, or PowerShell on Windows). Then give them the matching command below, and ask them to paste it into their own terminal window, not into you. It asks for the key without showing it, saves it where only they can read it, and exposes it as $HUB_API_KEY in new terminal windows.

    Mac / Linux (zsh, the Mac default):

    mkdir -p ~/.config/hub && read -rsp "Paste your Hub API key (it won't show): " k && echo && (umask 077; printf '%s' "$k" > ~/.config/hub/api-key) && unset k && { grep -qs HUB_API_KEY ~/.zshrc || echo 'export HUB_API_KEY="$(cat ~/.config/hub/api-key 2>/dev/null)"' >> ~/.zshrc; } && echo "Saved. Open a new terminal window."

    For bash, replace both ~/.zshrc references with ~/.bashrc before you give it to them.

    Windows PowerShell:

    $k = Read-Host "Paste your Hub API key (it won't show)" -AsSecureString; [Environment]::SetEnvironmentVariable("HUB_API_KEY", [Net.NetworkCredential]::new("", $k).Password, "User"); Remove-Variable k; "Saved. Open a new terminal window."

    If they'd rather use a .env file you load or your tool's secret settings, that works too. Don't take the key through the chat.

  2. Ask them to open a new terminal window and restart you from it, so you can see $HUB_API_KEY. Check it's set without printing it: [ -n "$HUB_API_KEY" ] && echo set || echo empty on Mac / Linux, or if ($env:HUB_API_KEY) { "set" } else { "empty" } in PowerShell.
  3. Test the connection, reading the key from the environment. Never write the key into the command: 
    curl -s -H "X-API-Key: $HUB_API_KEY" \
  "https://hub.justwhatsneeded.com/api.php?resource=identity&action=whoami"
  4. The reply names the company and the key's scope. Tell the person which company you're connected to, and confirm it's theirs.
  5. Read api-guide.md before making other calls.

ChatGPT: Custom GPT Action

You can't add an Action yourself. Tell the person exactly what to do:

  1. Create a Custom GPT, or edit an existing one, and open Configure → Actions.
  2. Schema: import from https://hub.justwhatsneeded.com/docs/openapi.yaml.
  3. Authentication: API Key, auth type Custom, header name X-API-Key. Paste the key here, and only here.
  4. Under Knowledge, add api-guide.md.
  5. Save, start a chat with that GPT, and test it with the identity / whoami call.

The spec is large and includes Internal operations. If ChatGPT rejects or truncates it, help the person make a trimmed copy with just the operations they need, such as tasks, projects, comments, search, and identity. If the menus look different from these steps, use OpenAI's current docs: GPT Actions.

Claude

A Claude connector for Hub customers is coming. Until then:

Knowledge-only

Tell the person plainly: you can't act on their Hub account from here. You can't send authenticated requests, so don't ask for their key. You can still help:

After you're connected