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

# Environments

> Sandbox and live share one host - the environment is selected by the key you exchange, not by the URL.

Expys has two environments, **sandbox** and **live**. They share one API host:
the environment is a property of the credential, not the URL. Routing is enforced
server-side from the token, so you never switch base URLs to change environments.

| Environment | Catalog                                                           | Use                              |
| ----------- | ----------------------------------------------------------------- | -------------------------------- |
| `sandbox`   | A seeded demo catalog (offers, points currency, redeemable drops) | Build and test without real data |
| `live`      | Your real program data                                            | Production                       |

## How the environment is selected

1. You create a **sandbox** or **live** Org-API-Key in the portal.
2. Your backend exchanges that key for a member token. The token carries the
   environment.
3. The SDK's `environment` option is declarative - it labels the credential (and
   appears in the `User-Agent`) but does not change the host. Set it to match the
   key you used so the two never disagree.

<Note>
  A sandbox key cannot read live data and vice versa. If you see empty results or
  `403`s, confirm the key's environment matches the `environment` you configured.
</Note>

## Configuring the environment

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { type Environment, initialize } from "@expys/sdk";

  const token = process.env.EXPYS_MEMBER_TOKEN;
  if (!token) {
    throw new Error(
      "Set EXPYS_MEMBER_TOKEN (a member token from your backend's /v1/auth/exchange)",
    );
  }

  // Default to sandbox for safe experimentation; pass EXPYS_ENV=live to go live.
  const environment: Environment =
    process.env.EXPYS_ENV === "live" ? "live" : "sandbox";

  const expys = initialize({
    baseUrl: process.env.EXPYS_BASE_URL,
    environment,
    // orgId is optional and only surfaces in the User-Agent for attribution.
    orgId: process.env.EXPYS_ORG_ID,
    token,
    // Identify your app in the User-Agent alongside the SDK and environment.
    userAgentSuffix: "examples/environments",
  });

  async function main(): Promise<void> {
    console.log(`using the ${environment} environment`);
    const { data } = await expys.listOffers({ limit: 5 });
    console.log(`fetched ${data.length} offers`);
  }
  ```

  ```swift Swift theme={null}
  import ExpysSDK
  import Foundation

  @main
  struct EnvironmentsExample {
    static func main() async throws {
      let environment = ProcessInfo.processInfo.environment
      guard let token = environment["EXPYS_MEMBER_TOKEN"] else {
        fatalError("Set EXPYS_MEMBER_TOKEN (a member token from your backend's /v1/auth/exchange)")
      }
      let baseURL =
        environment["EXPYS_BASE_URL"].flatMap(URL.init(string:))
        ?? ExpysConfiguration.defaultBaseURL

      // Default to sandbox for safe experimentation; pass EXPYS_ENV=live to go live.
      let selected: ExpysEnvironment = environment["EXPYS_ENV"] == "live" ? .live : .sandbox

      let client = ExpysClient(
        configuration: ExpysConfiguration(
          token: token,
          environment: selected,
          baseURL: baseURL,
          // orgID is optional and only surfaces in the User-Agent for attribution.
          orgID: environment["EXPYS_ORG_ID"],
          // Identify your app in the User-Agent alongside the SDK and environment.
          userAgentSuffix: "examples/environments"
        )
      )

      print("using the \(selected.rawValue) environment")
      let offers = try await client.listOffers(limit: 5)
      print("fetched \(offers.data.count) offers")
    }
  }
  ```

  ```kotlin Kotlin theme={null}
  package com.expys.sdk.examples.environments

  import com.expys.sdk.ExpysClient
  import com.expys.sdk.ExpysConfiguration
  import com.expys.sdk.ExpysEnvironment
  import kotlinx.coroutines.runBlocking

  fun main() = runBlocking {
    val token = System.getenv("EXPYS_MEMBER_TOKEN")
      ?: error("Set EXPYS_MEMBER_TOKEN (a member token from your backend's /v1/auth/exchange)")
    val baseUrl = System.getenv("EXPYS_BASE_URL") ?: ExpysConfiguration.DEFAULT_BASE_URL

    val sandbox = ExpysClient.create(
      ExpysConfiguration(token = token, environment = ExpysEnvironment.SANDBOX, baseUrl = baseUrl),
    )
    val live = ExpysClient.create(
      ExpysConfiguration(token = token, environment = ExpysEnvironment.LIVE, baseUrl = baseUrl),
    )

    println("sandbox offers: ${sandbox.listOffers(limit = 1).`data`.size}")
    println("live offers: ${live.listOffers(limit = 1).`data`.size}")
  }
  ```
</CodeGroup>

## Base URL

The canonical host is `https://api.expys.com` - the default in all three SDKs.
You can point at a different deployment with the `baseUrl` option. See the
[configuration reference](/guides/configuration).