Domains

Create or update a domain

Changed on Oct 9, 2026

Idempotent create-or-update. Uses the key field in the body to identify the domain. On first apply the domain is created; subsequent applies update it. dataPlaneId is optional at creation, resolved from the environment's data planes when omitted, and immutable afterwards. When dryRun is true, the endpoint validates the payload without persisting; the returned domain carries a dryRunErrors list (empty on success, populated with validation errors otherwise).

put/organizations/{orgId}/environments/{envId}/domains

Request

Base URL
http://localhost:8093/automation
URL
http://localhost:8093/automation/organizations/{orgId}/environments/{envId}/domains
Auth
HTTP bearer

Path parameters

orgIdstring required

Identifier of the organization that owns the environment.

envIdstring required

Identifier of the environment the resource belongs to.

Query parameters

dryRunboolean

When true, validates the payload without persisting. The returned domain includes a dryRunErrors field.

Request body

alertEnabledboolean

Whether alerting is enabled for the domain.

createdAtstring date-time

Creation timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

dataPlaneIdstring

Identifier of the data plane this domain is connected to. Optional at creation and resolved from the environment's data planes when omitted. Immutable afterwards: an apply that names a different one is rejected.

descriptionstring

Human-readable description of the domain.

enabledboolean

Whether the domain handles incoming authentication and authorization requests.

keystring required

Stable, immutable identifier for the domain within its environment. Lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. Used to identify the domain on create-or-update.

masterboolean

Whether this is the master domain of its environment. A master domain may perform cross-domain token introspection.

namestring required

Human-readable name of the domain.

pathstring required

Context path the domain is served under, relative to the gateway. Must start with a slash.

tagsstring[]

Sharding tags that control which gateways deploy this domain.

updatedAtstring date-time

Last-update timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

vhostModeboolean

Whether the domain is exposed through its virtual hosts rather than the default context path. When true, vhosts must be supplied.

Example request

{
  "accountSettings": {
    "accountBlockedDuration": 7200,
    "defaultIdentityProviderForRegistration": "users-idp",
    "loginAttemptsResetTime": 600,
    "maxLoginAttempts": 10,
    "mfaChallengeAttemptsResetTime": 600,
    "mfaChallengeMaxAttempts": 3,
    "redirectUriAfterRegistration": "https://app.example.com/welcome",
    "redirectUriAfterResetPassword": "https://app.example.com/signin",
    "rememberMeDuration": 604800,
    "resetPasswordCustomFormFields": [
      {
        "key": "email",
        "label": "Email",
        "type": "email"
      }
    ]
  },
  "certificateSettings": {
    "fallbackCertificate": "default"
  },
  "corsSettings": {
    "allowedHeaders": [
      "Authorization",
      "Content-Type"
    ],
    "allowedMethods": [
      "GET",
      "POST",
      "PUT",
      "DELETE"
    ],
    "allowedOrigins": [
      "https://app.example.com"
    ]
  },
  "dataPlaneId": "default",
  "description": "An example authentication domain",
  "key": "example-domain",
  "name": "Example domain",
  "path": "/example-domain",
  "saml": {
    "certificate": "signing-cert",
    "entityId": "https://auth.example.com/saml2/idp/entity"
  },
  "secretExpirationSettings": {
    "expiryTimeSeconds": 7776000
  },
  "tags": [
    "eu",
    "production"
  ],
  "tokenExchangeSettings": {
    "allowedActorTokenTypes": [
      "urn:ietf:params:oauth:token-type:access_token",
      "urn:ietf:params:oauth:token-type:id_token"
    ],
    "allowedRequestedTokenTypes": [
      "urn:ietf:params:oauth:token-type:access_token",
      "urn:ietf:params:oauth:token-type:id_token"
    ],
    "allowedSubjectTokenTypes": [
      "urn:ietf:params:oauth:token-type:access_token",
      "urn:ietf:params:oauth:token-type:id_token"
    ],
    "trustedIssuers": [
      {
        "issuer": "https://issuer.example.com",
        "jwksUri": "https://issuer.example.com/.well-known/jwks.json",
        "userBindingCriteria": [
          {
            "attribute": "emails.value",
            "expression": "{#token['email']}"
          }
        ]
      }
    ]
  },
  "vhosts": [
    {
      "host": "auth.example.com",
      "path": "/customers"
    }
  ],
  "webAuthnSettings": {
    "origin": "https://auth.example.com",
    "relyingPartyId": "auth.example.com",
    "relyingPartyName": "Example Inc."
  },
  "webProtectionSettings": {
    "csp": {
      "directives": [
        "default-src 'self'",
        "script-src 'self'",
        "upgrade-insecure-requests"
      ]
    },
    "xframe": {
      "action": "DENY"
    },
    "xss": {
      "action": "1; mode=block"
    }
  }
}

Response

The created or updated domain. When dryRun is true the domain includes a dryRunErrors field with any validation errors.