# Getting started

Everything you create lives in a project, projects live in a workspace, and the workspace holds the plan, the Balance and the team. Every service is reachable four ways: the dashboard, plain HTTPS (`https://harakumo.com/api/…`), the JavaScript SDK and the CLI. An AI assistant connected over MCP uses the same API, with your permissions.

New here? The Quickstart builds a working app with a database, browser uploads and payments, step by step. Its app is a server app, so its deploy step needs Pro and up; the other steps work on the free plan.

## The pieces

| Level | What it is |
| --- | --- |
| Account | You: an email address, a password and optional two-factor sign-in. |
| Workspace | Where billing and people live: one plan, one Balance, one team with roles. Signing up creates a personal workspace; you can create more and be invited to others. |
| Project | One app. It has its own address (`https://<slug>.harakumo.app`), environment variables and resources. |
| Resource | A database, bucket, function, auth pool, payment account, vector collection, memory store, agent or media asset inside a project. |

## Install

**SDK (Node 18 or newer)**

```bash
npm install @harakumo/sdk
```

**CLI**

```bash
npm install -g @harakumo/cli
harakumo login --key hk_live_…     # saved to ~/.harakumo/config.json
harakumo docs                      # these docs, in the terminal
```

## Make your first call

1. Create a key in Dashboard → Settings → API access (owners and admins can). It is shown once; store it as `HARAKUMO_API_KEY`.
2. Send it as a Bearer token. The same key works for every service and every interface.

**curl**

```bash
curl https://harakumo.com/api/projects \
  -H "Authorization: Bearer $HARAKUMO_API_KEY"
```

**SDK**

```js
import Harakumo from '@harakumo/sdk';

const hk = new Harakumo({ apiKey: process.env.HARAKUMO_API_KEY });
const { projects, org } = await hk.projects.list();
```

> Keys are secrets: use them from servers, scripts and CI, never in a browser or a mobile app. For sign-in from a browser, auth pools have a publishable client id instead (see Auth pools).

## Where to go next

- Quickstart — signup to a live app with a database, storage and payments (the deploy step needs Pro and up).
- API keys & authentication — full, read-only and project keys, and which to give an app.
- Limits & scaling — every number, and how each service behaves under load.
- Errors & rate limits — what each status and code means.
- AI connector (MCP) — run all of it from Claude or ChatGPT.