# Deploy from your app (for partners)

> For platforms that build sites — a person connects Livops once, and your "Deploy" button sends the files straight to Livops.

Source: https://livops.dev/en/docs/apps

This page is for platforms that build sites and apps (AI app builders, site builders, IDEs). Your user makes a project with you, presses **Deploy**, and the site opens on Livops. No token to copy: the person presses "Allow" once.

## How it works

1. The first time a person presses **Deploy**, you send them to Livops's consent page.
2. They sign in to Livops (or sign up), pick a team and press **Allow**.
3. Livops sends them back to your site with a `code`, which you exchange for a token.
4. Your server uploads the files as a zip, creates a project and watches the build.
5. Next time the person just presses **Deploy** — with the token you kept.

This is standard **OAuth 2.1** (authorization code + PKCE). Any OAuth library works.

## 1. Registering your app

In the cabinet, open **Account → My apps** and enter two things:

- your app's name — exactly what the consent page shows;
- your redirect address (`redirect_uri`), e.g. `https://app.example/livops/callback` — `https` only, up to 5.

Press **Create app** and copy the `client_id`. There is no client secret: PKCE and the pre-registered redirect address are what protect the exchange.

Your app works for everyone at once. Its consent page shows your email beside its name and says Livops has not checked the name. For the **Verified partner** badge, write to the Livops team. Renaming the app takes the badge off.

## 2. Connecting a person

For every connection, make a random `code_verifier` (43–128 characters) and derive the `code_challenge`:

```text
code_challenge = BASE64URL( SHA256(code_verifier) )   # no =
```

Send the person to:

```text
https://livops.uz/oauth/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https://app.example/livops/callback
  &scope=deploy
  &code_challenge=<code_challenge>
  &code_challenge_method=S256
  &state=<random value>
```

After they allow it, Livops returns:

```text
https://app.example/livops/callback?code=lvc_...&state=<the same value>&iss=https://livops.uz
```

Check that `state` is the one you sent. If the person refused — `?error=access_denied`.

Exchange the code within 60 seconds (it works once):

```bash
curl https://livops.uz/api/mcp/oauth/token \
  -d grant_type=authorization_code \
  -d code=lvc_... \
  -d redirect_uri=https://app.example/livops/callback \
  -d client_id=<client_id> \
  -d code_verifier=<code_verifier>
```

```json
{
  "access_token": "lvo_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "lvr_...",
  "scope": "deploy"
}
```

- The `access_token` lasts 1 hour.
- A `refresh_token` gets you a new pair. Each refresh spends the old `refresh_token` — always keep the latest. Sending a spent one again ends the whole connection (it is treated as stolen).
- Unused for 30 days, the person has to connect again.

```bash
curl https://livops.uz/api/mcp/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=lvr_... \
  -d client_id=<client_id>
```

Keep the tokens on your server only. Never hand them to a browser: on a request with a `Cookie`, `Origin` or `Sec-Fetch-*` header, Livops ignores the token.

## 3. Sending the files

Zip the project folder (no `node_modules`, `dist` or `.git` needed) and upload it:

```bash
curl https://livops.uz/api/uploads/zip \
  -H 'Authorization: Bearer lvo_...' \
  -F file=@site.zip
```

```json
{
  "id": "22ac5e77-d7b2-46ef-b7ba-a9b38220c964",
  "files": 4,
  "bytes": 844,
  "kind": "site",
  "preset": { "name": "vite", "label": "Vite", "build": "npm run build", "output": "dist" }
}
```

Livops detects the framework itself (`preset`). Limits: 200 MB and 5,000 files per upload, and 1 GB per account of uploads not yet made into projects.

## 4. Creating the project

```bash
curl https://livops.uz/api/projects \
  -H 'Authorization: Bearer lvo_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-site",
    "kind": "site",
    "source": "upload",
    "sourceRef": "22ac5e77-d7b2-46ef-b7ba-a9b38220c964",
    "preset": "vite",
    "env": [{ "name": "VITE_API_URL", "value": "https://api.example.com" }]
  }'
```

- `sourceRef` is the `id` from the upload's answer.
- `preset` is `preset.name` from the upload's answer. Without it the project is made as plain HTML.
- `env` is optional. `"secret": true` hides the value from later reads.

The answer carries the project and its first build together:

```json
{
  "project": { "id": "7088b8bf-…", "slug": "my-site", "preset": "vite", "status": "draft" },
  "deploy":  { "id": "7d8644bd-…", "status": "queued" }
}
```

Keep `project.id` next to the person's project — later deploys go through it.

## 5. Build status and address

```bash
curl https://livops.uz/api/deploys/<deploy.id> \
  -H 'Authorization: Bearer lvo_...'
```

`status` values:

| Status | Meaning |
| --- | --- |
| `queued` | Waiting in line |
| `building` | Building |
| `live` | The site is up |
| `failed` | Failed — the reason is in `error` and `log` |
| `cancelled` | Withdrawn before it started |
| `awaiting_payment` | Built; starting it needs a top-up |

Poll every 3–5 seconds. Once it is `live`, the site's address is on the project:

```bash
curl https://livops.uz/api/projects/<project.id> \
  -H 'Authorization: Bearer lvo_...'
# { ..., "host": "my-site.livops.app" }
```

## 6. Later deploys

Upload the new files as a zip again and hand them to the project:

```bash
curl https://livops.uz/api/projects/<project.id>/deploys \
  -H 'Authorization: Bearer lvo_...' \
  -H 'Content-Type: application/json' \
  -d '{ "upload": "<new upload id>" }'
```

With no body (`-d '{}'`) the same files are built again. If a build is already queued — `409 deploy_in_progress`: wait for it to finish.

## 7. Variables

```bash
curl -X PATCH https://livops.uz/api/projects/<project.id>/env \
  -H 'Authorization: Bearer lvo_...' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "VITE_API_URL", "value": "https://api.example.com" }'
```

Several at once: `{ "vars": [{ "name": "...", "value": "..." }, ...] }`. A new value applies from the next deploy.

## What the app can do

The person sees exactly this list on the consent page.

- **Can:** upload files, create projects in this team, read the projects **it created**, deploy them again, write their variables, cancel a build.
- **Cannot:** see the team's other projects (they answer `404`), read variables, delete anything, touch domains, databases, billing or account settings.

To create projects, the person must be the **owner** of the team they picked. They can disconnect the app at any time under **Account → Connected AI apps** — its tokens stop working at once.

## Errors

An error always has one shape, with `message` in the person's language (`Accept-Language: uz` or `ru`):

```json
{ "code": "deploy_in_progress", "message": "…", "field": "…" }
```

| Code | What to do |
| --- | --- |
| `401` | The token expired — refresh it with the `refresh_token`. If the refresh answers `invalid_grant` too, connect the person again |
| `403 address_unproven` | The person has not confirmed their email — show the message |
| `403 forbidden` | The call is not open to apps, or the person is not the team's owner |
| `404` | No such project, or another app created it |
| `402 build_needs_credit`, `402 daily_builds_used` | A plan limit — send the person to the Livops cabinet |
| `409 deploy_in_progress` | A build is already running |
| `413` | The files are too large |
| `429` | Too many requests — wait a moment and retry |
