---
order: 7
slug: "/docs/v1/start/environments"
title: "Environments"
section: "Start here"
description: "Keep Sandbox and Live credentials, customer licenses and webhook traffic separate without confusing payment-provider mode."
audience: "all"
level: "beginner"
last_updated: "2026-10-17"
version: "v1"
related: ["/docs/v1/start/quickstart","/docs/v1/start/glossary"]
draft: false
---
[Sandbox](/docs/v1/start/glossary#sandbox) tests your integration; [Live](/docs/v1/start/glossary#live) serves your real software [customers](/docs/v1/start/glossary#customer).

## What you will learn
- Which records are environment-specific and which configuration is shared.
- How the API chooses an environment.
- How platform allowances and payment modes differ from licensing environments.

## Prerequisites
- Read [core concepts](/docs/v1/start/core-concepts).
- Identify your [product](/docs/v1/start/glossary#product)'s [public App ID](/docs/v1/start/glossary#public-app-id) and the relevant credential type.

## Isolation rules
| Record or operation | Behaviour |
| --- | --- |
| Product, [product plan](/docs/v1/start/glossary#product-plan), [feature](/docs/v1/start/glossary#feature) definitions | Shared within your [organization](/docs/v1/start/glossary#organization) |
| Customer and [license](/docs/v1/start/glossary#license) | Stored in Sandbox or Live |
| [Device](/docs/v1/start/glossary#device) and [activation token](/docs/v1/start/glossary#activation-token) | Inherit the associated license's environment |
| [Developer API key](/docs/v1/start/glossary#developer-api-key) | Bound to one product, organization and environment |
| Outgoing [webhook](/docs/v1/start/glossary#webhook) endpoint | Has its own environment selection |
| Workspace usage | Counted across the organization, not a fresh allowance per environment |

## Request selection
[Activation](/docs/v1/start/glossary#activation) reads X-Environment, trims and uppercases it, accepts SANDBOX or LIVE, and defaults a missing header to SANDBOX. Send it explicitly to avoid relying on a default.
[Developer](/docs/v1/start/glossary#developer) management endpoints derive the environment from the authenticated developer API key. X-Environment does not override the key.
Validation and deactivation derive the environment from the activation token's license. They do not select a different license from an X-Environment header.

## Dashboard switch
The dashboard environment switch changes the current viewing/creation context. It does not convert an existing license or customer. Products and plans remain shared.
Free is Sandbox evaluation only. Live key, webhook and license creation needs the appropriate paid entitlement and eligible subscription. Existing customer-license validation is handled separately from creation limits.

## Payment modes are separate
Stripe or Mollie Test/Live mode controls [platform subscription](/docs/v1/start/glossary#platform-subscription) payments. It is not the licensing environment. A test subscription payment is not a real-money sale; changing payment mode does not migrate a Sandbox license.

## Safe testing
1. Select Sandbox before creating the test license.
2. Use synthetic customer data and a test mailbox you control.
3. Set SANDBOX explicitly in the client.
4. Keep Sandbox server keys separate from Live secrets.
5. Label test state directories so they cannot overwrite production client state.
Expected result: your tests create and modify only Sandbox records.

## Expected result
You know which environment each credential and record belongs to, and do not expect two independent monthly usage pools.

## Common mistakes
- Sending a Sandbox key with LIVE: it cannot activate that Live license.
- Sending X-Environment: LIVE beside a Sandbox developer key: the key remains Sandbox.
- Assuming an environment switch migrates data: issue the intended Live records deliberately.

## Security notes
Do not print either environment's secret keys in logs. Environment names are not a substitute for secret scoping and authorization. Do not run validation experiments against real customer credentials.

## Troubleshooting
| Symptom | Cause | Fix |
| --- | --- | --- |
| INVALID_LICENSE 404 during activation | Key, supplied email, product or environment did not match | Check all four privately; the response deliberately does not disclose which identifier exists |
| LICENSE_NOT_FOUND 404 on management | The key's organization/product/environment does not match the resource | Use the correctly scoped key and license ID |
| Live option is unavailable | The workspace lacks eligible paid Live access | Review Billing; do not bypass the dashboard gate |
| Dashboard appears to have no licenses | You selected the other environment | Switch viewing context without modifying records |

## Next steps
Complete the [Sandbox quickstart](/docs/v1/start/quickstart), then the [go live checklist](/docs/v1/start/go-live-checklist).

## Related
- [Authentication](/docs/v1/start/authentication)
- [Core concepts](/docs/v1/start/core-concepts)
- [Current integration limitations](/docs/v1/integration-notes)