Environment Configuration Export / Import Guide

This guide explains how to export and import environment configurations in the InCountry Portal. Use it to back up settings, migrate configurations between environments, or update Border and AgentCloak configuration programmatically.

---

What is Export / Import?

Every InCountry environment has a configuration that covers:

• Key-alias mappings — how data fields are mapped to storage keys
• Border endpoints — redaction and unredaction rules for your API traffic
• AgentCloak (MCP) — AI agent data protection rules
• Access Policies — data access control rules
• Data Firewall — IP allowlist settings
• Activated Countries — which country POPs are active

The export downloads all of this as a single JSON file. The import applies a (modified) JSON file back to the environment. This is the foundation for both manual configuration management and automated CI/CD pipelines.

---

Prerequisites

Before you begin, you need:

1. Access to the InCountry Portal with edit rights on the target environment.

2. Your Environment ID — visible in the browser URL when you open an environment:

   https://portal.incountry.com/environments/<YOUR-ENVIRONMENT-ID>

   

---

Exporting the Configuration

1. Open your environment in the Portal and scroll down to the "Manage environment configuration" widget.

   

2. Click "Export environment configuration".

   The browser immediately downloads a JSON file named after your Environment ID (e.g., 705b1cc0-0259-41c7-885e-0d1ffdc79aa8.json). No confirmation dialog appears — the download starts right away.

3. Open the downloaded file in any text editor or JSON tool. You will see a structure like:

   {
     "version": 1,
     "environmentId": "705b1cc0-0259-41c7-885e-0d1ffdc79aa8",
     "activatedCountries": [ ... ],
     "cloakSettings": [ ... ],
     "policies": [ ... ],
     "keyMapping": { ... },
     "dataFirewall": { ... },
     "countries": {
       "se-mt-01": {
         "border": {
           "service": { "name": "my-border" },
           "configurations": [ ... ]
         },
         "agentCloak": {
           "mcpServers": [ ... ],
           "mcpProxies": [ ... ]
         }
       }
     }
   }

Important

Keep the entire file intact when editing. The import expects the full structure — never strip out sections you did not intend to change. Only modify the specific fields you want to update.

---

Editing the Configuration

Edit the downloaded JSON to make your changes. Common modifications:

What to change	Where in the JSON
Border target URL	countries.<key>.border.configurations[n].target
Add/update redaction rule	countries.<key>.border.configurations[n].redactions[n].strategies
CORS allowed origin	countries.<key>.border.configurations[n].cors.Access-Control-Allow-Origin
Key-alias mapping	keyMapping.<table>.fields.<field>.map_to
Firewall IP allowlist	dataFirewall.countries.<country>.whitelist.ip
AgentCloak MCP server URL	countries.<key>.agentCloak.mcpServers[n].mcp_server_url

Redaction strategy reference

When editing redaction rules, use a strategy from this list:

Strategy	Best for	Example fields
alphaNumericPersistent	Names (deterministic)	$.fullName, $.firstName
emailPersistent	Emails (deterministic)	$.email, $.contactEmail
numeric	Phone numbers, amounts	$.phone, $.mobile
defaultDateISO	Dates (fixed to 1970-01-01)	$.dateOfBirth, $.dob
alphaNumeric	Addresses, URLs, generic text	$.address, $.url
password	Passwords, secrets	$.password, $.secret
fixed	Fixed replacement value	$.country, $.locale
masking	Partial masking (shows prefix)	$.cardNumber, $.name

---

Importing the Configuration

1. Scroll to the "Manage environment configuration" widget and click "Import environment configuration".

   

2. A file picker dialog opens. Select your edited JSON file and confirm.

3. The Portal applies the configuration. If the import succeeds, the environment updates immediately. If there is a validation error, the portal shows an error message — the environment is not changed.

tip

To verify that the import took effect, export again right after and compare the downloaded file with the one you uploaded. They should match on all fields you changed.

---

Authentication for API / Script Access

API Key (simple, for direct curl calls)

If you want to call the export/import API directly with curl or a script:

1. In the environment dashboard, find the "API Keys" widget and click "+ Create API Key".

   

2. Fill in:

   • Name — a descriptive label (e.g., migration-dev)
   • Scopes → Environments — check Export and Import
   • Expiration — choose Never, 30 days, 90 days, or a custom date

3. Click Create and copy the generated key immediately — it will not be shown again.

4. Use it in curl:

   # Export
   curl -s -H "X-API-Key: <YOUR_API_KEY>" \
     "https://portal.incountry.com/api/environments/<ENV_ID>/export" \
     -o config.json
   
   # Import
   curl -s -X POST -H "X-API-Key: <YOUR_API_KEY>" \
     -F "file=@config.json" \
     "https://portal.incountry.com/api/environments/<ENV_ID>/import"

---

Migration Client (OAuth2, for automated pipelines)

For automated workflows such as CI/CD, use the Migration client. It generates OAuth2 client credentials scoped specifically to env:export env:import, following the principle of least privilege.

1. In the "Manage environment configuration" widget, under "Migration client", click "+ Create migration client".

   

2. The portal generates and displays:

   Field	Description
   Environment ID	The target environment UUID
   Authentication endpoint	OAuth2 token URL (e.g., https://auth.incountry.com/oauth2/token)
   Portal address	API base URL (e.g., https://portal.incountry.com/api)
   Scope	env:export env:import
   Client ID	OAuth2 client identifier
   Client Secret	Secret — copy now, it will not be shown again

3. Click Download or Copy all to save the credentials.

Warning

The Client Secret is shown only once. Save it securely (e.g., as a GitHub Actions secret or in a secrets manager) before closing this panel.

---

Automating with CI/CD

Once you have a Migration client, you can automate export/import in a pipeline. The general pattern is:

1. Export the current configuration from the source environment.
2. Apply changes programmatically (patch JSON fields, inject environment-specific values).
3. Import the modified configuration to the target environment.
4. Verify by re-exporting and comparing with the expected state.

This enables GitOps-style configuration management: your desired configuration lives in source control, and a pipeline applies it on every merge to main.

GitHub Actions example (concept)

name: Sync environment configuration

on:
  push:
    branches: [main]
    paths:
      - 'templates/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get OAuth2 token
        id: token
        run: |
          TOKEN=$(curl -s -X POST "${{ secrets.AUTH_ENDPOINT }}" \
            -d "grant_type=client_credentials" \
            -d "client_id=${{ secrets.CLIENT_ID }}" \
            -d "client_secret=${{ secrets.CLIENT_SECRET }}" \
            -d "scope=env:export env:import" \
            | jq -r '.access_token')
          echo "token=$TOKEN" >> "$GITHUB_OUTPUT"

      - name: Export current configuration
        run: |
          curl -s -H "Authorization: Bearer ${{ steps.token.outputs.token }}" \
            "${{ secrets.PORTAL_ADDRESS }}/environments/${{ secrets.ENV_ID }}/export" \
            -o baseline.json

      - name: Apply template overrides
        run: |
          jq '. * $overlay' baseline.json \
            --slurpfile overlay templates/agentcloak.template.json \
            > final.json

      - name: Import updated configuration
        run: |
          curl -s -X POST \
            -H "Authorization: Bearer ${{ steps.token.outputs.token }}" \
            -F "file=@final.json" \
            "${{ secrets.PORTAL_ADDRESS }}/environments/${{ secrets.ENV_ID }}/import"

Required secrets in your GitHub repository:

Secret	Value
AUTH_ENDPOINT	Authentication endpoint from Migration client
CLIENT_ID	Client ID from Migration client
CLIENT_SECRET	Client Secret from Migration client
PORTAL_ADDRESS	Portal address from Migration client
ENV_ID	Your Environment ID

---

Troubleshooting

Symptom	Likely cause	Fix
Import returns 400	Malformed JSON or missing required fields	Validate JSON; ensure version, environmentId, and countries are present
Import returns 401	Invalid or expired API key / token	Regenerate credentials in the Portal
Import returns 403	Key lacks Import scope	Re-create the API key with the Import scope enabled
Fields unchanged after import	Merged with wrong base	Always start from a fresh export; never construct the payload from scratch
Client Secret lost	Panel was closed before copying	Click Renew in the Migration client panel to generate a new secret