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

# Production & Sandbox Environments

> Understand how to use Production and Sandbox environments to test safely before going live — across gu1 production and sandbox accounts for safe testing.

## Overview

gu1 provides **dual environments** for every organization, allowing you to test configurations and workflows safely before deploying to production:

* **Production**: Your live environment with real data and integrations
* **Sandbox**: A safe testing environment with simulated providers and mock data

<Note>
  When you sign up, both environments are created automatically with the same team members and permissions.
</Note>

## Understanding Organizations

In gu1, an **Organization** represents your company account. Each organization has:

* **Unique Organization ID**: A UUID that identifies your organization (e.g., `8e2f89ab-c216-4eb4-90eb-ca5d44499aaa`)
* **Two Paired Environments**: Production and Sandbox, linked together but with separate data
* **Team Members**: Users with specific roles (Owner, Admin, Member) synchronized across both environments
* **Isolated Data**: All entities, rules, investigations, and configurations are scoped to the organization

<Info>
  **Finding Your Organization IDs**: Navigate to [app.gu1.ai/api-keys](https://app.gu1.ai/api-keys) to see both your **Production** and **Sandbox** Organization IDs with convenient copy buttons.
</Info>

### Why Organization IDs Matter

When making API requests to [api.gu1.ai](https://api.gu1.ai), you **must** include the `X-Organization-ID` header to tell gu1 which organization and environment you're targeting:

```bash theme={null}
# Production request (using Production Organization ID)
curl -X GET https://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: 8e2f89ab-c216-4eb4-90eb-ca5d44499aaa"

# Sandbox request (using Sandbox Organization ID)
curl -X GET https://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: 86122d3c-6dfc-4afa-9c46-aaf841262c7e"
```

<Warning>
  **Never hard-code Organization IDs in public repositories.** Store them as environment variables in your application.
</Warning>

## Key Differences

<CardGroup cols={2}>
  <Card title="Production Environment" icon="rocket" color="#3b82f6">
    * Real provider integrations
    * Actual costs for API calls
    * Live data and transactions
    * Blue "Live" badge in UI
    * Full rate limits based on plan
  </Card>

  <Card title="Sandbox Environment" icon="flask" color="#f97316">
    * Mock provider responses
    * Zero costs (simulated data)
    * Test data only
    * Orange "Test" badge in UI
    * Limited rate limits (100 req/h)
    * 🧪 Global banner indicator
  </Card>
</CardGroup>

## How Environments Work

**Important**: Production and Sandbox are **completely isolated** from each other:

* **Separate Data**: Entities, rules, investigations, and configurations are independent
* **Separate API Keys**: Each environment has its own API keys
* **Same Team**: Team members and permissions are automatically synchronized
* **No Cross-Talk**: Actions in Sandbox never affect Production data

<Info>
  Think of them as two parallel universes: anything you do in Sandbox stays in Sandbox, and Production remains untouched.
</Info>

## Switching Environments in the Dashboard

You control which environment you're viewing through the **environment switcher** at [app.gu1.ai](https://app.gu1.ai):

<Steps>
  <Step title="Log in to app.gu1.ai">
    Access your dashboard at [app.gu1.ai](https://app.gu1.ai)
  </Step>

  <Step title="Locate the Switcher">
    Find the environment toggle in the top-right corner of the header
  </Step>

  <Step title="Click to Switch">
    Click to toggle between "Production" and "Sandbox"
  </Step>

  <Step title="Instant Update">
    The dashboard updates instantly to show data from the selected environment
  </Step>
</Steps>

<Warning>
  **Sandbox Indicator**: When in Sandbox mode, a global orange banner (🧪 Sandbox Mode) appears at the top of every page so you always know where you are.
</Warning>

## API Requests and Environments

When making API requests to [api.gu1.ai](https://api.gu1.ai), the environment is determined by the **Organization ID** you send:

```bash theme={null}
# This request goes to PRODUCTION (using Production Org ID)
curl -X GET https://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_prod_..." \
  -H "X-Organization-ID: 8e2f89ab-c216-4eb4-90eb-ca5d44499aaa"

# This request goes to SANDBOX (using Sandbox Org ID)
curl -X GET https://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_devel_..." \
  -H "X-Organization-ID: 86122d3c-6dfc-4afa-9c46-aaf841262c7e"
```

<Note>
  The dashboard switcher at **app.gu1.ai** only affects what you see in the UI. For API requests to **api.gu1.ai**, use the correct Organization ID header.
</Note>

<Tip>
  **Finding Your Organization IDs**: Go to the **API Keys** page in your dashboard at [app.gu1.ai](https://app.gu1.ai) to see both Production and Sandbox Organization IDs with copy-to-clipboard buttons.
</Tip>

## API Keys per Environment

API keys are **environment-specific** and their behavior depends on which **Organization** (Production or Sandbox) they belong to:

### Key Prefixes

API key prefixes indicate the **infrastructure environment** where the gu1 platform is running, not whether the key belongs to a Production or Sandbox organization:

* `gk_development_...` - Keys created when gu1 platform runs locally (development)
* `gk_staging_...` - Keys created when gu1 platform runs on staging servers
* `gk_production_...` - Keys created when gu1 platform runs on production servers (live gu1 platform)

<Warning>
  **Important**: The prefix does NOT indicate if your organization is Production or Sandbox. Both your Production and Sandbox organizations will have the same prefix based on where the gu1 platform is deployed.
</Warning>

<Info>
  **Example**: When you create an API key at [app.gu1.ai](https://app.gu1.ai) (live platform), both your Production organization keys AND your Sandbox organization keys will have the `gk_production_...` prefix. The Organization ID in the `X-Organization-ID` header determines which data you access.
</Info>

### Rate Limits

Rate limits depend on the **Organization type**, not the key prefix:

* **Sandbox Organizations**: Fixed at **100 requests/hour** (regardless of plan)
* **Production Organizations**: Based on your plan:
  * Freemium: 60 req/min
  * Startup: 120 req/min
  * Growth: 600 req/min
  * Enterprise: 1,200+ req/min

### Provider Behavior

* **Sandbox Organizations**: Always use mock providers (simulated responses, no real API costs)
* **Production Organizations**: Use real provider integrations

<Note>
  When creating an API key, the environment fields are **read-only** and automatically set to your current environment. The Organization ID determines whether it's a Sandbox or Production key.
</Note>

## Mock Providers in Sandbox

In Sandbox, all provider integrations return **simulated responses** instead of making real API calls:

<AccordionGroup>
  <Accordion title="Compliance Screening (Sanctions, PEP, Adverse Media)">
    * Returns varied risk profiles: clean, low, medium, high, critical
    * Simulates realistic response times (100-2000ms)
    * Includes mock person/entity data with aliases
    * No actual costs incurred
  </Accordion>

  <Accordion title="Webhooks">
    * Webhooks are **simulated**, not sent to actual URLs
    * All attempts are logged with simulated success/failure
    * View logs in the Sandbox section
  </Accordion>

  <Accordion title="Rule Actions">
    * Actions like "Send email" or "Create task" are **simulated**
    * All simulations are logged for review
    * Allows testing complex workflows without side effects
  </Accordion>
</AccordionGroup>

<Tip>
  Mock responses are designed to mimic production behavior closely, so your testing is as realistic as possible.
</Tip>

## Configuration Promotion

Once you've tested and validated your configuration in Sandbox, you can **promote** it to Production:

<Steps>
  <Step title="Configure in Sandbox">
    Create and test your rules, field mappings, schemas, and data lists in Sandbox
  </Step>

  <Step title="Validate">
    Use the promotion validation endpoint to check for conflicts
  </Step>

  <Step title="Promote">
    Promote individual configurations or in bulk
  </Step>

  <Step title="Rollback if Needed">
    View promotion history and rollback if necessary
  </Step>
</Steps>

<Info>
  Learn more about configuration promotion in the [Environments API Reference](/en/api-reference/environments).
</Info>

## Best Practices

<AccordionGroup>
  <Accordion title="Always Test in Sandbox First">
    Before creating or modifying rules, test them thoroughly in Sandbox to avoid false positives or workflow issues in Production.
  </Accordion>

  <Accordion title="Use Sandbox for Training">
    Onboard new team members in Sandbox where they can experiment without affecting live data.
  </Accordion>

  <Accordion title="Create Separate API Keys">
    Use different API keys for Sandbox and Production in your codebase to avoid accidental cross-environment requests.
  </Accordion>

  <Accordion title="Monitor the Global Banner">
    The orange Sandbox banner is your reminder that you're in test mode. Always check before making important changes.
  </Accordion>

  <Accordion title="Review Promotion History">
    After promoting configurations, verify they work as expected in Production and check the promotion history for an audit trail.
  </Accordion>
</AccordionGroup>

## Sandbox Limitations

<Warning>
  Sandbox environments have the following limitations:

  * **Rate Limits**: 100 requests/hour (vs. plan-based in Production)
  * **Data Retention**: Sandbox data may be cleared periodically
  * **Expiry**: Depending on your plan, Sandbox may have an expiration date
  * **Mock Data Only**: Cannot access real provider integrations by default
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="Can I upgrade my Sandbox rate limits?">
    Sandbox rate limits are fixed at 100 req/h to encourage testing in reasonable volumes. If you need higher limits for load testing, please contact support.
  </Accordion>

  <Accordion title="Are team permissions synchronized?">
    Yes! When you add or remove team members in either environment, the changes are automatically synchronized to the paired environment.
  </Accordion>

  <Accordion title="Can I use real providers in Sandbox?">
    By default, no. Sandbox uses mock providers to avoid costs. Contact support if you have a specific need to test real integrations in Sandbox.
  </Accordion>

  <Accordion title="What happens when Sandbox expires?">
    Depending on your plan, Sandbox may have an expiration date. You'll receive warnings before expiry, and you can extend or make it permanent by upgrading your plan.
  </Accordion>

  <Accordion title="Can I delete my Sandbox?">
    Sandbox and Production are paired environments. If you want to remove your Sandbox, please contact support.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="API Authentication" icon="key" href="/en/api-reference/authentication">
    Learn how to authenticate with API keys
  </Card>

  <Card title="Configuration Promotion" icon="arrow-up" href="/en/api-reference/environments">
    Promote configs from Sandbox to Production
  </Card>

  <Card title="Entities API" icon="database" href="/en/api-reference/entities/overview">
    Create and manage entities in your environment
  </Card>

  <Card title="Rules Engine" icon="brain" href="/en/api-reference/rules">
    Configure risk rules per environment
  </Card>
</CardGroup>