# Environments

Tag devices as production, staging or development, send to one environment at a time, and switch each on or off.

> **Not the APNs sandbox:**
>
> This is your product's environment, not Apple's APNs host, which Native Notify picks per token, so debug and release builds both work in any environment.

## Tag a device

Every device belongs to one environment: `production`, `staging` or `development`. Pass `environment` when you [register](/docs/push/registration):

```json
{
  "appId": 123,
  "appToken": "yourAppToken",
  "deviceId": "A1B2C3D4-install-key",
  "platform": "android",
  "environment": "staging",
  "tokens": { "fcmToken": "c4d5e6…" }
}
```

- A new device without `environment` is `production`.
- Re-registering with a different value moves the device and its tokens. Without one, the device keeps its tag.
- An unknown value is `400 invalid_environment`.

## Send to an environment

Pass the same field on a [send](/docs/push/sending). A send without it is a production send.

```json
{
  "appId": 123,
  "appToken": "yourAppToken",
  "title": "Staging check",
  "message": "Only staging devices receive this.",
  "environment": "staging",
  "audience": { "type": "all" }
}
```

Every audience is filtered to the send's environment, and the response echoes it as `environment`. Each [inbox](/docs/push/web-inbox) entry records it too. A [test send](/docs/push/verification) goes to the device or token you name, whatever its environment. A [schedule rule](/docs/push/scheduling) sends only to its own environment.

## List and switch environments

```text
GET  https://app.nativenotify.com/api/universal/environments/:appId/:appToken
POST https://app.nativenotify.com/api/universal/environments/:appId/:appToken
```

The GET answers `200` with all three environments, always in this order:

```json
{
  "environments": [
    { "key": "production", "label": "Production", "enabled": true, "deviceCount": 1280, "tokenCount": 1302 },
    { "key": "staging", "label": "Staging", "enabled": true, "deviceCount": 4, "tokenCount": 4 },
    { "key": "development", "label": "Development", "enabled": false, "deviceCount": 1, "tokenCount": 1 }
  ]
}
```

`enabled` is the effective state: an environment that was never switched is on. `deviceCount` counts tagged devices, and `tokenCount` every token they hold, live and retired.

The POST takes `key` (or the alias `environment`) and a boolean `enabled`, and answers with the same shape as the GET:

```json
{ "key": "development", "enabled": false }
```

While an environment is off, new registrations into it and new sends to it answer `403 environment_disabled`, before anything is written or sent. Stored devices and tokens are untouched, so switching it back on restores delivery. Switching production off affects every call that doesn't name an environment.

## Errors

| Status | Code                                             | Meaning                                                                     |
| ------ | ------------------------------------------------ | --------------------------------------------------------------------------- |
| `400`  | `invalid_body`, `missing_field`, `invalid_field` | Bad body, no `key` or `enabled`, a non-boolean `enabled`, or a bad `appId`. |
| `400`  | `invalid_environment`                            | `key` isn't one of the three environments.                                  |
| `403`  | `environment_disabled`                           | A registration or send targeted a switched-off environment.                 |
| `404`  | `app_not_found`                                  | The app isn't one this caller can access.                                   |
