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

# iOS Auth & Environments

> Configure your Desmo keys, environments, and base URLs for the iOS SDK.

## Keys and environments in Desmo

Desmo uses API keys to identify **who** is sending data and **which environment** it belongs to.

At a high level:

* **Publishable keys** (start with `pk_`) are used by the iOS SDK in your app.
* **Secret keys** (start with `sk_`) are used only by your backend and internal tools.

Each key is created for a specific **environment**:

* `sandbox` – for development and test traffic.
* `live` – for production deliveries.

Your Desmo dashboard is where you create and revoke keys; this page focuses on how they are used from iOS.

## Configuring the iOS SDK with a key

When you call `Desmo.setup`, you pass your **publishable key** and an environment:

```swift theme={null}
import DesmoTraceSDK

Desmo.setup(
    key: "pk_sandbox_XXXXXXXXXXXXXXXX",
    environment: .sandbox
)
```

Rules enforced by the SDK:

* The key **must** start with `pk_`, otherwise `Desmo.setup` throws `DesmoClientError.invalidApiKey` and logs an error.
* The key is sent on every HTTP request in the `Desmo-Key` header:

  ```http theme={null}
  Desmo-Key: pk_sandbox_XXXXXXXXXXXXXXXX
  ```

You should **never** embed secret (`sk_...`) keys in your app—those belong only on your backend.

## Choosing an environment

The `DesmoEnvironment` type controls **which Desmo backend** the SDK talks to:

```swift theme={null}
Desmo.setup(
    key: "pk_sandbox_XXXXXXXXXXXXXXXX",
    environment: .sandbox  // or .live
)
```

Today, both `.sandbox` and `.live` point to `https://api.getdesmo.io`, but they are treated as separate environments in the control plane (keys, tenants, projects).

Recommended usage:

* Use `.sandbox` during development and QA.
* Use `.live` in your production app.

If your team sets up dedicated staging or internal endpoints in the future, you can update the SDK to route those environments without changing your app code.

## Rotating and revoking keys

When you create or revoke keys in the dashboard:

* Existing apps using an old **publishable** key will continue to work **until you revoke that key**.
* Once revoked, requests using that key will start failing with authorization errors.

Rotation checklist:

1. Create a new publishable key for the environment you need.
2. Update your app configuration (or remote config) to use the new key.
3. Ship an app update and wait for adoption.
4. Revoke the old key once you are confident no important traffic is using it.

## Security guidelines

* Treat keys as **credentials**:
  * Do not commit real keys into public repos.
  * Prefer using Xcode build settings or a remote config system to inject keys.
* Never log keys in production logs.
* Use separate keys for sandbox and live environments to avoid test data mixing with real deliveries.

With keys and environments configured, your app can safely send telemetry to the right tenant and environment. Next, set up logging and troubleshooting so you can see what the SDK is doing.