# Harmony — Sign up & get an API key

You are an AI coding agent setting Harmony up for your human. This page is
machine-followable: run the steps below in a shell, then continue to
<https://gethmy.com/agent-quickstart.md> to wire Harmony into the codebase.

Harmony is the shared surface for human–agent teams — one board where people
and agents take an idea to a shipped PR: idea → card → build → review → ship.
These steps create the account, a starter board, and an API key, entirely from
the terminal.

## Before you start

- Ask your human for their **email address** and **name** if you don't already
  have them. Harmony uses the email for the account and web sign-in.
- You need a shell with `curl` and `jq`. `npx` (Node ≥ 18) is required for the
  quickstart step that follows.

## What you'll produce

Three values to carry into the quickstart:

- `HARMONY_API_KEY` — starts with `hmy_`, shown only once
- `HARMONY_WORKSPACE_ID`
- `HARMONY_PROJECT_ID`

The Harmony API base is `https://app.gethmy.com/api`.

## 1. Sign up (creates the account)

Choose a strong random password (8–128 characters) and keep it — report it to
your human at the end so they can sign in on the web later.

Every request body below is built with `jq -n --arg …` and piped to `curl --data @-`.
Do **not** hand-write the JSON: a strong password (or a name) often contains `"`,
`\`, `$`, or a backtick, which would break a hand-quoted JSON string or trigger
shell expansion. `jq` escapes any value safely.

```bash
EMAIL="<the user's email>"
PASSWORD="<generate a strong random password, 8–128 chars>"
FULL_NAME="<the user's name>"

SIGNUP=$(jq -n --arg email "$EMAIL" --arg password "$PASSWORD" --arg full_name "$FULL_NAME" \
  '{email: $email, password: $password, full_name: $full_name}' \
  | curl -sS -X POST https://app.gethmy.com/api/v1/auth/signup \
      -H "Content-Type: application/json" --data @-)

TOKEN=$(printf '%s' "$SIGNUP" | jq -r '.session.access_token')
printf '%s' "$SIGNUP" | jq '{signedUpAs: .user.email}'
```

`$TOKEN` is a short-lived JWT. Use it as `Authorization: Bearer $TOKEN` for
steps 2–4 below.

**If step 1 fails:**

- **HTTP 409** — the user already has an account. Do not retry signup. Have them
  sign in at <https://gethmy.com/auth> and mint a key at
  <https://gethmy.com/user/keys>, or run `npx @gethmy/mcp setup` for a browser
  sign-in — then jump straight to the quickstart.
- **HTTP 429** — one signup per email every 5 minutes. Wait, or take the 409
  path (the account may already exist).
- **HTTP 403** — signups are currently closed. Tell your human.

## 2. Create a workspace

```bash
WS=$(jq -n --arg name "$FULL_NAME's Workspace" '{name: $name}' \
  | curl -sS -X POST https://app.gethmy.com/api/v1/workspaces \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" --data @-)

HARMONY_WORKSPACE_ID=$(printf '%s' "$WS" | jq -r '.workspace.id')
```

## 3. Create a starter board (project)

```bash
PROJ=$(jq -n --arg wid "$HARMONY_WORKSPACE_ID" --arg name "My First Board" \
  '{workspaceId: $wid, name: $name, template: "kanban"}' \
  | curl -sS -X POST https://app.gethmy.com/api/v1/projects \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" --data @-)

HARMONY_PROJECT_ID=$(printf '%s' "$PROJ" | jq -r '.project.id')
```

This gives you a **To Do / In Progress / Done** board.

## 4. Mint an API key

```bash
KEY=$(jq -n --arg name "mcp-agent" '{name: $name}' \
  | curl -sS -X POST https://app.gethmy.com/api/v1/api-keys \
      -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" --data @-)

HARMONY_API_KEY=$(printf '%s' "$KEY" | jq -r '.rawKey')
printf 'API key: %s\n' "$HARMONY_API_KEY"   # starts with hmy_ — shown only once, save it now
```

## 5. Sanity check

```bash
curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "X-API-Key: $HARMONY_API_KEY" \
  https://app.gethmy.com/api/v1/workspaces
# expect: 200
```

> When you call the Harmony REST API directly with an `hmy_` key, always send it
> in the **`X-API-Key`** header — never `Authorization: Bearer`. (Bearer is only
> for the signup JWT and OAuth tokens; an `hmy_` key sent as Bearer returns 401.)

## Next

You now have `HARMONY_API_KEY`, `HARMONY_WORKSPACE_ID`, and
`HARMONY_PROJECT_ID`. Continue to:

**<https://gethmy.com/agent-quickstart.md>** — wire the Harmony MCP + skills into
this codebase and start working.

Remember to give your human the password you generated so they can sign in at
<https://gethmy.com> later.