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

# Quickstart — create an environment in 5 minutes

> Copy-paste path from zero to a working environment with its own API key, webhook target, and first run.

This quickstart takes you from "I have a Nexio org with a live integration" to "I'm sending traffic to a dev environment that doesn't touch production." About 5 minutes.

## Prerequisites

* An existing Nexio org with `api_keys:manage` permission.
* A live API key (`nx_live_*`) for the API calls below. You can copy yours from the portal at `/api-keys`.
* Curl or any HTTP client.

## 1. Create the environment

```bash theme={null}
curl -X POST https://api.usenexio.com/api/v1/environments \
  -H "Authorization: Bearer $NEXIO_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "dev"
  }'
```

Save the returned `id` — you'll see it stamped on every run from this environment.

## 2. Create an API key for the environment

The portal API-key route accepts a `environment_slug` field that binds the new key to a specific environment row. The key prefix is derived from the slug:

| Slug          | Prefix       |
| ------------- | ------------ |
| `live`        | `nx_live_`   |
| `test`        | `nx_test_`   |
| anything else | `nx_<slug>_` |

The `/api/api-keys` route on `platform.usenexio.com` is authenticated via your **WorkOS portal session cookie** — not a bearer API key — because portal management routes are session-scoped. The easiest path today is:

1. Sign in at [platform.usenexio.com](https://platform.usenexio.com).
2. Open browser DevTools → **Application → Cookies** and copy the value of the `wos-session` cookie.
3. Use the cookie in your curl call:

```bash theme={null}
curl -X POST https://platform.usenexio.com/api/api-keys \
  -H "Cookie: wos-session=$WOS_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dev integration",
    "environment_slug": "dev"
  }'
```

Response (`201 Created`):

```json theme={null}
{
  "id": "...",
  "keyPrefix": "nx_dev_a3f2",
  "key": "nx_dev_<64 hex chars>"
}
```

Copy the `key` field — it's shown only once. The rest of this guide reads it as `$NEXIO_DEV_KEY`:

```bash theme={null}
export NEXIO_DEV_KEY="nx_dev_..."
```

A first-class portal UI for in-modal environment selection (and a bearer-authed `POST /api/v1/environments/{slug}/keys` for fully programmatic provisioning) lands as a follow-up. Until then, the session-cookie curl above is the canonical per-environment create path.

## 3. Send your first environment run

```bash theme={null}
curl -X POST https://api.usenexio.com/api/v1/engines/$ENGINE_SLUG/runs \
  -H "Authorization: Bearer $NEXIO_DEV_KEY" \
  -H "Content-Type: application/json" \
  -d @input.json
```

Response (`202 Accepted`):

```json theme={null}
{
  "run_id": "11111111-1111-1111-1111-111111111111",
  "status": "PENDING"
}
```

## 4. Verify the run landed in your environment

```bash theme={null}
curl https://api.usenexio.com/api/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $NEXIO_DEV_KEY"
```

In the portal, open `/runs`, select `dev` from the Environment dropdown — your run is there. Switch back to `live` — no dev runs are visible.

## 5. Set up an environment webhook (optional)

From the portal:

1. Open `/webhooks` → ensure `dev` is selected in the Environment dropdown.
2. **Create endpoint**, paste the URL you want dev events delivered to.
3. The signing secret is shown once — copy it into your dev webhook handler.

Now any run in the dev environment delivers to your dev webhook URL with the dev signing secret. Production webhook traffic continues to flow to your live endpoint unchanged.

## Where to go next

* **Limits and gotchas**: [Environments guide](/guides/environments)
* **Authentication and key types**: [Authentication reference](/api-reference/authentication)
* **Engine version pinning** (coming in Phase 2): pin an environment to a specific engine version so behavior is frozen for repro and regression testing.

## Common questions

**Will my existing `nx_test_*` keys still work?**
Yes — they're grandfathered into a `test` environment row that was auto-created during the Phase 0 rollout. No action required. New non-prod integrations should use `nx_*` keys.

**Are environment runs billed?**
Yes, environment runs count toward your org's usage. Per-environment attribution rolls up to org for billing. Talk to your account contact about how non-prod traffic is metered for your contract.

**Can I share a webhook signing secret across environments?**
No — secrets are per-endpoint per-environment by design, so a leaked dev secret can't be used to forge live webhook deliveries.