# Install & test your app before moderation

Get your **draft** application onto a test location you control and make your first
authenticated calls — **before** submitting for moderation. This is a supported,
self-serve flow. You should not need to read any source code to finish it.

Prefer an AI-assisted workflow? The [Integrations Hub MCP](/en/developers/integrations-hub-mcp)
can plan and run the owner-side application lifecycle from a connected MCP client.

## What you'll have at the end

- Your application linked to your test location with status **`active`**.
- A **system-user token** authorized to read that test location's data.
- A repeatable way to reinstall on any location you own — no moderation required.


## Before you start

| You need | Where to get it |
|  --- | --- |
| **Application ID** and **Partner ID** | Developer console — the console labels both clearly on your application's **General info** page |
| **Partner Token** | Marketplace → **Account settings** (appears automatically after registration). See [How to Get API Keys](/en/get-api-key) |
| **System User Token** | In the application's **API Access** settings, enter the system user's **User ID**, save, and copy the generated **User Token**. Configure the required credentials and application access rights before installation |
| **Owner login** on a **test location you control** | Any location where your user has the **Manage user rights** permission |


Throughout this guide the examples use **application `2391`** and test **location
`4564`**. Replace tokens with your own — never commit them.

## How installation works

Installing an app on a location is a **two-step handshake**. Neither step alone
installs the app:

```
  owner grants access            partner confirms (within 12 hours)
uninstalled ─────────────▶ pending ─────────────────────────────▶ active
                              │
                              └── no confirm within 12h ─▶ stays pending (reconnect)
```

| Status | Meaning |
|  --- | --- |
| `pending` | Owner connected the app; waiting for the partner to confirm |
| `active` | Partner confirmed; system user linked, data calls allowed |
| `freezed` | Previously active, frozen (e.g. non-payment) |


> **Draft apps are installable but hidden.** The public app-store card for a draft
returns `404`. That is expected — install via the API below, or via the console
**“Link to request a review”** (see [Test from the console](#test-from-the-console-no-api)).


## Step 1 — Owner connects the app (`grant_access`)

The location owner grants the app access. This creates the link in **`pending`**.

- **Host:** `https://api.alteg.io/api/v1` (main API)
- **Auth:** combined partner + owner user token
- **Permission:** the user must have **Manage user rights** on the location


```bash
curl -X POST \
  'https://api.alteg.io/api/v1/company/4564/marketplace/applications/2391/grant_access' \
  -H 'Accept: application/vnd.api.v2+json' \
  -H 'Authorization: Bearer <PARTNER_TOKEN>, User <OWNER_USER_TOKEN>'
```

**Expected:** `201 Created`. The link is now `pending` (or immediately `active` for
non-public/whitelisted apps — fast install).

Reference: [Connect an Application to a Location](/en/developers/openapi#tag/Marketplace/operation/marketplace_location_grant_access).

## Step 2 — Partner confirms (installation callback)

Confirm the installation with your **Partner Token**. This moves the link to
**`active`**, links the system user, and delivers your integration settings.

- **Host:** `https://app.alteg.io` — **root, not** `https://api.alteg.io/api/v1`
- **Auth:** Partner Token only
- **Deadline:** within **12 hours** of Step 1


```bash
curl -X POST \
  'https://app.alteg.io/marketplace/partner/callback' \
  -H 'Accept: application/vnd.api.v2+json' \
  -H 'Authorization: Bearer <PARTNER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"salon_id": 4564, "application_id": 2391}'
```

**Expected:** `201`. The link is now `active`.

> The `salon_id` body field and the `/marketplace/salon/…` path segment are the
**Location ID** and Location scope — legacy identifier names kept for
backwards compatibility.


Reference: [Application Installation for a Location](/en/developers/openapi#tag/Marketplace/operation/marketplace_notification_settings_callback).

## Step 3 — Verify

Check the installation status:

```bash
curl -X GET \
  'https://app.alteg.io/marketplace/salon/4564/application/2391' \
  -H 'Accept: application/vnd.api.v2+json' \
  -H 'Authorization: Bearer <PARTNER_TOKEN>'
```

**You're done when** `data.connection_status.status` is **`active`**.

You can also confirm the location shows up for your system user:

```bash
curl -X GET \
  'https://api.alteg.io/api/v1/companies?my=1' \
  -H 'Accept: application/vnd.api.v2+json' \
  -H 'Authorization: Bearer <PARTNER_TOKEN>, User <SYSTEM_USER_TOKEN>'
```

The **system-user token** is the token in the application's **API Access → User
Token** field; use it as `User <...>` for data calls against installed locations.
For how system-user rights work, see [Access to the API](https://alteg.io/en/support/knowledge-base/6756027118621-access-to-the-api/).

Reference: [Application Status Data for Any Location](/en/developers/openapi#tag/Marketplace/operation/get_marketplace_integration_status).

## Test from the console (no API)

If you just want to place a draft on your own location through the UI:

1. In the developer console open your application's **General info**.
2. Copy the **“Link to request a review”**.
3. Open it while signed in as an **admin of your test location**.
4. Press **Connect**.


This runs Step 1 for you. Full walkthrough:
[Step-by-step guide to placement in the marketplace](https://alteg.io/en/support/knowledge-base/6745848593181-step-by-step-guide-to-placement-in-the-marketplace).

## If something goes wrong

| Symptom | Cause | Fix |
|  --- | --- | --- |
| Step 1 returns `403` | User lacks **Manage user rights**, or install is blocked for the location | Use an owner/admin login; contact your account manager if blocked |
| Link stuck in `pending` | Step 2 never sent, or sent after the 12-hour window | Reconnect (Step 1), then send the callback within 12 hours |
| Callback returns `404` | Wrong host — you called `api.alteg.io/api/v1/...` | Use the `https://app.alteg.io` **root**: `https://app.alteg.io/marketplace/partner/callback` |
| Data calls return `401` | Missing or wrong `User <...>` token | Use the system-user token from the application's **API Access → User Token** field |


## Related

- [Integrations Hub MCP](/en/developers/integrations-hub-mcp) — hosted AI-assisted application setup and rollout
- [API documentation start page](/en#quickstarts) — choose the right guide for your integration
- [How to Get API Keys (v1 and v2)](/en/get-api-key) — partner and user tokens
- [Access to the API](https://alteg.io/en/support/knowledge-base/6756027118621-access-to-the-api/) — user tokens and permissions (KB)
- [Connecting integrations via the marketplace](https://alteg.io/en/support/knowledge-base/6746045060381-connecting-the-integration-via-the-marketplace) — the install callback (KB)
- [Developer Tools reference](/en/developers/openapi) — full marketplace endpoint reference