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

# Environments and secrets

> Configure staging vs production and manage authKey securely

Use this guide when you need to pick the right Lomadee environment, wire credentials into your deployment, and keep partner secrets out of source control.

## Choose an environment

The SDK accepts an optional `environment` field on construction:

```typescript theme={null}
import { Lomadee } from '@thelomadee/sdk';

// Production (default when omitted)
const production = new Lomadee({
  authKey: process.env.LOMADEE_AUTH_KEY!,
  environment: 'production',
});

// Staging — use credentials from onboarding
const staging = new Lomadee({
  authKey: process.env.LOMADEE_AUTH_KEY!,
  environment: 'staging',
});
```

| Value          | When to use                                                                        |
| -------------- | ---------------------------------------------------------------------------------- |
| `'production'` | Live partner integrations. This is the default when `environment` is not set.      |
| `'staging'`    | Pre-production testing. Use the staging `authKey` and credentials from onboarding. |

The SDK routes each resource client to the correct service hosts for the selected environment. You do not pass base URLs or per-service overrides.

<Note>
  Staging and production may use different `authKey` values. Confirm which key belongs to which environment with your Lomadee contact—do not assume one key works in both.
</Note>

## Store the authKey as a secret

Your `authKey` is equivalent to a long-lived API credential. Treat it like a database password:

1. **Load from environment variables** (or your platform's secret manager) at process startup.
2. **Never commit** the key to git, `.env` files checked into the repo, Docker image layers intended for public registries, or client-side bundles.
3. **Restrict access** in CI/CD and production to the roles that need it.
4. **Rotate on compromise**—contact Lomadee support if a key may have leaked.

### Recommended pattern

```typescript theme={null}
import { Lomadee } from '@thelomadee/sdk';

function createLomadeeClient() {
  const authKey = process.env.LOMADEE_AUTH_KEY;

  if (!authKey) {
    throw new Error('LOMADEE_AUTH_KEY is not configured');
  }

  return new Lomadee({
    authKey,
    environment: process.env.LOMADEE_ENVIRONMENT === 'staging'
      ? 'staging'
      : 'production',
  });
}
```

Use a factory or dependency-injection container so tests can substitute a mock client without touching real credentials.

`@thelomadee/sdk` is published on the public npm registry. Installing it does not require a GitHub token or a custom `.npmrc`. Keep `authKey` as the only runtime secret.

## Keep the SDK server-side

The SDK attaches `authKey` as the `x-auth-key` header on every outbound request. Any process that loads the SDK therefore holds full partner access.

| Do                                                                     | Don't                                                       |
| ---------------------------------------------------------------------- | ----------------------------------------------------------- |
| Call the SDK from API routes, workers, cron jobs, and backend services | Import the SDK in React/Vue/Svelte frontends or mobile apps |
| Pass **results** (not credentials) to clients                          | Log full request headers or echo `authKey` in error pages   |
| Run integration tests against staging with scoped secrets              | Share one production key across unrelated teams or repos    |

## Local development checklist

* [ ] `LOMADEE_AUTH_KEY` is set in your shell or local `.env` (gitignored)
* [ ] Quickstart script runs successfully with `sdk.terms.latest()`
* [ ] `environment: 'staging'` is used only when intentionally testing against staging

## Related guides

* [Quickstart](/docs/sdk/quickstart) — first install and verified request
* [Error handling](/docs/sdk/guides/error-handling) — surface failures without leaking secrets in logs
* [How the SDK works](/docs/sdk/concepts/how-the-sdk-works) — shared client, timeout, and resource layout