# Activate, deactivate, or discard custom domains

`management_groups.change_domain_lifecycle`

Activate, deactivate, or discard custom domains. Read branding immediately first and pass its revision. An explicit request to complete whitelabelling includes activating the requested addresses when ready. Domain activation affects the Management Group; confirm that shared scope matches the request. Activate checks current DNS and HTTPS and enables a configured, verified sender; an unverified sender stays disabled. Only branding.domain_activation.status=active means activation completed, even when the call succeeds. If waiting, allow retry_after_seconds, read branding again, and retry with a fresh revision and request ID within the current session. Reuse an ID only for a lost response or the same completed attempt. Waiting does not schedule later activation. If user action is needed or the session cannot keep waiting, state what remains incomplete and the next step. Once active, offer frontend_links.open_portal unchanged so the user can open the branded portal using browser sign-in handoff. Deactivate disables custom addresses and the sender but keeps setup. Discard removes only an unactivated replacement draft and preserves current live addresses.

[Branding guide](https://docs.staging.levr.ai/mcp/resources/management_group_branding.md)

Availability depends on live discovery and your access to the record. Do not infer MCP calls from REST paths.

Operation: write. Required OAuth scopes: mcp.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "client_request_id": {
      "maxLength": 255,
      "minLength": 1,
      "type": "string"
    },
    "expected_revision": {
      "description": "Copy branding.revision unchanged from management_groups.get_branding; not an integer draft revision.",
      "maxLength": 64,
      "minLength": 64,
      "type": "string"
    },
    "lifecycle_action": {
      "description": "Read domains[].status and tls_status from management_groups.get_branding. Activate checks current DNS and TLS before turning on a ready pair; deactivate turns off live domains; discard removes an unactivated replacement draft.",
      "enum": [
        "activate",
        "deactivate",
        "discard"
      ],
      "type": "string"
    },
    "management_group_slug": {
      "description": "Copy management_group_slug from management_groups.list. Prefix: mgmt_.",
      "maxLength": 255,
      "minLength": 1,
      "type": "string"
    },
    "user_confirmed": {
      "const": true,
      "type": "boolean"
    }
  },
  "required": [
    "management_group_slug",
    "expected_revision",
    "lifecycle_action",
    "client_request_id",
    "user_confirmed"
  ],
  "type": "object"
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "oneOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ]
    },
    {
      "not": {
        "required": [
          "data"
        ]
      },
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ]
    }
  ],
  "properties": {
    "data": {
      "additionalProperties": false,
      "properties": {
        "branding": {
          "additionalProperties": false,
          "properties": {
            "capabilities": {
              "type": "object"
            },
            "domain_activation": {
              "additionalProperties": false,
              "properties": {
                "blockers": {
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 3,
                  "type": "array"
                },
                "retry_after_seconds": {
                  "maximum": 60,
                  "minimum": 1,
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "status": {
                  "enum": [
                    "active",
                    "ready",
                    "waiting",
                    "blocked"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "status",
                "blockers",
                "retry_after_seconds"
              ],
              "type": "object"
            },
            "domains": {
              "items": {
                "additionalProperties": false,
                "properties": {
                  "activated_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "cname_target": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "dns_records": {
                    "type": [
                      "array",
                      "object",
                      "null"
                    ]
                  },
                  "host": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "last_checked_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "normalized_error_code": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "normalized_error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "status": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "surface": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "tls_status": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "txt_record_name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "txt_record_value": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "surface",
                  "host",
                  "status",
                  "cname_target",
                  "txt_record_name",
                  "txt_record_value",
                  "dns_records",
                  "tls_status",
                  "normalized_error_code",
                  "normalized_error_message",
                  "last_checked_at",
                  "activated_at"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "email_sender": {
              "type": "object"
            },
            "frontend_links": {
              "additionalProperties": false,
              "properties": {
                "brand_assets": {
                  "format": "uri",
                  "maxLength": 4096,
                  "type": "string"
                },
                "domains": {
                  "format": "uri",
                  "maxLength": 4096,
                  "type": "string"
                },
                "legal_links": {
                  "format": "uri",
                  "maxLength": 4096,
                  "type": "string"
                },
                "open_portal": {
                  "description": "Durable, credential-free portal link. Offer unchanged after activation; the signed-in browser creates auth handoff on opening.",
                  "format": "uri",
                  "maxLength": 4096,
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "overview": {
                  "format": "uri",
                  "maxLength": 4096,
                  "type": "string"
                },
                "support_details": {
                  "format": "uri",
                  "maxLength": 4096,
                  "type": "string"
                }
              },
              "required": [
                "overview",
                "brand_assets",
                "domains",
                "support_details",
                "legal_links",
                "open_portal"
              ],
              "type": "object"
            },
            "managed_provider_count": {
              "type": "integer"
            },
            "management_group_slug": {
              "description": "Canonical mgmt_ identifier; copy the returned value unchanged.",
              "maxLength": 255,
              "minLength": 1,
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "profile": {
              "type": "object"
            },
            "public_contact_email": {
              "type": "string"
            },
            "readiness": {
              "type": "object"
            },
            "recent_activity": {
              "items": {
                "additionalProperties": false,
                "properties": {
                  "event": {
                    "type": "string"
                  },
                  "occurred_at": {
                    "type": "string"
                  }
                },
                "required": [
                  "event",
                  "occurred_at"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "revision": {
              "type": "string"
            }
          },
          "required": [
            "management_group_slug",
            "name",
            "managed_provider_count",
            "revision",
            "frontend_links",
            "profile",
            "domains",
            "public_contact_email",
            "email_sender",
            "readiness",
            "capabilities",
            "domain_activation"
          ],
          "type": "object"
        }
      },
      "required": [
        "branding"
      ],
      "type": "object"
    },
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string"
        },
        "details": {
          "additionalProperties": true,
          "description": "Optional bounded, agent-safe correction or recovery facts.",
          "type": "object"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "code",
        "message",
        "retryable"
      ],
      "type": "object"
    },
    "meta": {
      "additionalProperties": false,
      "properties": {
        "request_id": {
          "type": "string"
        }
      },
      "required": [
        "request_id"
      ],
      "type": "object"
    },
    "ok": {
      "description": "Whether the tool completed successfully.",
      "type": "boolean"
    }
  },
  "required": [
    "ok",
    "meta"
  ],
  "type": "object"
}
```

Check the result, then read the affected record to confirm your change.