Create an environment

curl --request POST \
  --url https://api.nango.dev/environments \
  --header 'Authorization: Bearer <NANGO-ACCOUNT-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "staging",
    "webhooks": {
      "primary_url": "https://app.example.com/webhooks/nango",
      "on_sync_completion_always": false
    }
  }'

{
  "data": {
    "id": 123,
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "staging",
    "is_production": false,
    "callback_url": "https://api.nango.dev/oauth/callback",
    "slack_notifications": false,
    "otlp_endpoint": null,
    "otlp_headers": [],
    "webhooks": {
      "primary_url": "https://app.example.com/webhooks/nango",
      "secondary_url": null,
      "on_sync_completion_always": false,
      "on_auth_creation": true,
      "on_auth_refresh_error": true,
      "on_sync_error": true,
      "on_async_action_completion": true,
      "on_connection_deletion": true,
      "signing_key": "5f1c0d2e-6a1b-4f3c-9d8e-7b6a5c4d3e2f"
    }
  }
}

POST

environments

curl --request POST \
  --url https://api.nango.dev/environments \
  --header 'Authorization: Bearer <NANGO-ACCOUNT-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "staging",
    "webhooks": {
      "primary_url": "https://app.example.com/webhooks/nango",
      "on_sync_completion_always": false
    }
  }'

{
  "data": {
    "id": 123,
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "staging",
    "is_production": false,
    "callback_url": "https://api.nango.dev/oauth/callback",
    "slack_notifications": false,
    "otlp_endpoint": null,
    "otlp_headers": [],
    "webhooks": {
      "primary_url": "https://app.example.com/webhooks/nango",
      "secondary_url": null,
      "on_sync_completion_always": false,
      "on_auth_creation": true,
      "on_auth_refresh_error": true,
      "on_sync_error": true,
      "on_async_action_completion": true,
      "on_connection_deletion": true,
      "signing_key": "5f1c0d2e-6a1b-4f3c-9d8e-7b6a5c4d3e2f"
    }
  }
}

Requires an Account API key with the account:environments:create scope. Create one from Account API keys in the dashboard.

Creates a new environment. Additional environments are limited by your pricing plan. Set is_production: true to create a production environment. This also requires account:environments:set_production. The reserved name prod is always production and cannot be combined with is_production: false. Pass webhooks to configure URLs and subscriptions. Set webhooks.signing_key to choose the environment’s webhook signing key. See Receive webhooks from Nango for delivery behavior, event types, and signature verification. webhooks.signing_key must be a UUID v4. You should generate it using a cryptographically secure random generator, such as crypto.randomUUID(). The security of a supplied key depends on how you generate and protect it; Nango validates its format but cannot verify its randomness. If omitted, Nango generates a secure random signing key. The response returns the complete environment settings, including the plaintext webhook signing key and environment uuid. Use the uuid to create an Environment API key or delete the environment. Creating an environment also creates a default full-access Environment API key, but the secret is not returned.

curl --request POST \
  --url https://api.nango.dev/environments \
  --header 'Authorization: Bearer <NANGO-ACCOUNT-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "staging",
    "webhooks": {
      "primary_url": "https://app.example.com/webhooks/nango",
      "on_sync_completion_always": false
    }
  }'

{
  "data": {
    "id": 123,
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "staging",
    "is_production": false,
    "callback_url": "https://api.nango.dev/oauth/callback",
    "slack_notifications": false,
    "otlp_endpoint": null,
    "otlp_headers": [],
    "webhooks": {
      "primary_url": "https://app.example.com/webhooks/nango",
      "secondary_url": null,
      "on_sync_completion_always": false,
      "on_auth_creation": true,
      "on_auth_refresh_error": true,
      "on_sync_error": true,
      "on_async_action_completion": true,
      "on_connection_deletion": true,
      "signing_key": "5f1c0d2e-6a1b-4f3c-9d8e-7b6a5c4d3e2f"
    }
  }
}

Authorizations

Authorization

string

header

required

An Environment API key from your Nango environment, or an Account API key for account-level endpoints.

Body

application/json

name

string

required

Environment name. Lowercase letters, digits, hyphens, and underscores only. Max 255 characters. The reserved name prod is always treated as production.

Maximum string length: 255

Pattern: ^[a-z0-9_-]+$

Example:

"staging"

is_production

boolean

Whether to mark the environment as production. Defaults to false, except for the reserved name prod.

callback_url

string<uri>

Custom OAuth callback URL for this environment.

hmac_key

string

deprecated

Legacy public-key authorization HMAC key. Use Connect sessions instead.

Maximum string length: 1000

hmac_enabled

boolean

deprecated

Whether legacy public-key authorization HMAC verification is enabled. Use Connect sessions instead.

slack_notifications

boolean

Whether Slack notifications are enabled for this environment.

otlp_endpoint

string

OpenTelemetry collector endpoint. Requires a plan with OpenTelemetry export. Pass an empty string to set an empty endpoint.

otlp_headers

object[]

Headers sent with OpenTelemetry export requests. Requires a plan with OpenTelemetry export. Maximum 100 headers.

Maximum array length: 100

Show child attributes

webhooks

object

Initial webhook settings. Omitted URLs default to null; omitted subscription flags default to true.

Show child attributes

Response

Successfully created an environment

data

object

required

Show child attributes

Getting started

Guides

Reference

Create an environment

Authorizations

Body

Response