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

# Getting Started

> Create your developer account, scaffold your app with the CLI, and make your first API call.

This guide walks you through every step from creating your Max AI developer account to making your first API call.

## Step 1: Get a Developer Account

To access the Max AI API, you need a developer account.

1. **Sign up at [app.maxcare.dev](https://app.maxcare.dev)** to get a developer account.
2. Once registered, sign in at [app.maxcare.dev](https://app.maxcare.dev) (staging).

## Step 2: Install the CLI

The Max AI CLI is the fastest way to create and develop apps.

```bash theme={null}
npm install -g @max-ai/cli
```

Authenticate with your developer account:

```bash theme={null}
max-ai auth login
```

This opens a browser window where you sign in with your Max AI account. The CLI stores your API key locally.

<Note>
  For CI or headless environments, you can pass an API key directly: `max-ai auth login --api-key <key> --platform-url https://api.maxcare.dev`
</Note>

## Step 3: Create Your App

Scaffold a new app with a single command:

```bash theme={null}
max-ai app init my-app
```

This prompts for app name, slug, and category, creates the app on the platform, scaffolds a Next.js project, and writes your `client_id` to `max-ai.app.toml`. See the [CLI Reference → Creating an App](/guides/cli#creating-an-app) for full output.

<Tip>
  You can also create apps from the [Developer Console](https://app.maxcare.dev/developer) if you prefer a web UI.
</Tip>

## Step 4: Develop Locally

<Note>
  The tunnel requires `cloudflared`. Install it first:

  * **macOS:** `brew install cloudflared`
  * **Linux/Windows:** see the [CLI Reference](/guides/cli#prerequisites)
</Note>

Start your local development environment:

```bash theme={null}
cd my-billing-app
max-ai app dev
```

This command:

* Starts your Next.js dev server
* Creates a Cloudflare Tunnel to expose your local server via HTTPS
* Registers your app as a **draft** on the platform
* Auto-installs the app in your organization for testing

Your draft app appears in the marketplace **only for your organization**, marked with a "Draft" badge.

### Seed Test Data

<Note>
  Coming soon — test data seeding is not yet available.
</Note>

## Step 5: Get Your API Key

Your app receives an API key when installed by an organization. For development, the CLI handles this automatically.

For manual API access, generate a key from the Developer Console:

1. Go to your app's settings page
2. Under **API Keys**, click **Generate New Key**
3. Select the scopes for this key — effective permissions will never exceed the scopes granted to your app by the clinic
4. Copy the key immediately — **it is only shown once**

Your API key looks like this:

```
max_dev_ak_SBA...01S
```

<Warning>
  Keep your API key secret. Never expose it in client-side code, public repositories, or logs. If your key is compromised, revoke it immediately and generate a new one.
</Warning>

## Step 6: Make Your First Request

Every API request requires an **Organization ID** in the `X-Organization-Id` header. This identifies which clinic's data you're accessing.

You can get the Organization ID from:

* **The App Bridge** — The [`@max-ai/app-bridge`](https://www.npmjs.com/package/@max-ai/app-bridge) SDK provides it automatically when your app is embedded in Max AI.
* **The API** — Call [`/v3/marketplace/me`](/api-reference/marketplace/get-app-identity) to get your app's identity and connected organization.

Verify your setup:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.maxcare.dev/v3/marketplace/me" \
    -H "Authorization: Bearer max_dev_ak_SBA...01S" \
    -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.maxcare.dev/v3/marketplace/me", {
    headers: {
      "Authorization": "Bearer max_dev_ak_SBA...01S",
      "X-Organization-Id": "7e2c8cfe-b7a9-4deb-986d-e7012589e72b",
    },
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.maxcare.dev/v3/marketplace/me",
      headers={
          "Authorization": "Bearer max_dev_ak_SBA...01S",
          "X-Organization-Id": "7e2c8cfe-b7a9-4deb-986d-e7012589e72b",
      },
  )
  print(response.json())
  ```
</CodeGroup>

### Successful Response

```json theme={null}
{
  "code": "success",
  "data": {
    "app": {
      "id": "app_2b6fe6754b674990bb07fa16ece694c3",
      "slug": "testapi",
      "liveVersionId": "apv_89ba6db5e6644a008849299672992970"
    },
    "organization": {
      "id": "org_7e2c8cfeb7a94deb986de7012589e72b"
    },
    "scopes": [
      "read:patients",
      "read:appointments",
      "read:providers",
      "read:bills",
      "read:claims",
      "read:notes",
      "read:emails"
    ]
  }
}
```

## Step 7: Deploy (Beta)

<Note>
  App deployment via the CLI is currently in beta.
</Note>

When your app is ready for production, set your hosting URL and deploy:

```bash theme={null}
max-ai app deploy
```

Then submit for review from the Developer Console. The Max AI team will review your app and approve or deny it with feedback.

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/guides/cli">
    Full CLI documentation with all commands and options.
  </Card>

  <Card title="App Development" icon="code" href="/guides/app-development">
    SDK packages, app lifecycle, and best practices.
  </Card>

  <Card title="Scopes" icon="shield-halved" href="/guides/scopes">
    Understand which scopes grant access to which endpoints.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Browse all available endpoints.
  </Card>
</CardGroup>