SmartZone credentials

SZ-MCP stores one SmartZone controller per organisation. Saving new credentials replaces what was there; there is no list of connections to choose between. The form is the SmartZone login card on Configure › Controller (/settings/controller). Every member can see which controller is saved, but only an organisation admin can save, test or delete it; others see “Only organisation admins can change or test the controller login.”

The form

Field	Required	Limit	Notes
Host / FQDN	Yes	253 characters	Bare hostname or IP. No scheme, no path — sz.example.com, not https://sz.example.com/
Port	Yes	8443 or 443 only	Defaults to 8443. Pick 443 for a controller behind NAT, a reverse proxy or the controller tunnel
Username	Yes	200 characters	A SmartZone admin username
Password	On first save, and whenever the host or port changes	500 characters	Leave blank when changing only the username or label to keep the stored one
Label	No	100 characters	Your own nickname. Not sent to the controller

Entering a host with a scheme, a path, a port or a user is rejected before anything is contacted. The dashboard shows Not saved: invalid_body; the API response carries the reason, host must be a bare FQDN or IP (no scheme, path, port or user).

The password is write-only

Once saved, the password is never returned — not to the dashboard, not through the API, not to Claude. The form shows a placeholder (••••••• (saved — leave blank to keep)) rather than the value.

It is stored in Cloudflare D1, encrypted with AES-256-GCM, and decrypted only in memory when a new service ticket has to be minted. See Where the password lives.

That is also why the password is optional on later saves: you can correct the username or label without re-entering it. A new host or port needs the password again, so the stored password is never sent to a host it was not entered for; without it the save stops with “Not saved: enter the password to save a new host or port.”

Note

Leaving the password blank has one side effect worth knowing: API version detection only runs when a password is supplied. An edit that keeps the stored password keeps the previously detected version too. Use Test connection if you want detection to run again.

API version detection

SmartZone’s API is versioned in the URL path, and controllers differ. Rather than asking you which version yours speaks, SZ-MCP detects it.

On Save & detect, it first asks the controller which versions it supports, with GET /wsg/api/public/apiInfo — a request that needs no credentials — and picks the newest version in the apiSupportVersions list. Then it logs in once, with that version. The detected version is stored and used for every subsequent call, on both the wifi and switches namespaces.

How many login attempts does a save cost?

One. The password is sent exactly once, to the newest version’s login. A host that does not answer apiInfo the way a SmartZone does gets no login at all: the save stops with not_smartzone before your password goes anywhere.

Caution

This is why a wrong password produces one clear login_failed. If your SmartZone locks accounts after repeated failures, a single bad save costs you one attempt.

Testing, rotating and deleting

Test connection

Test connection flushes the cached service ticket, decrypts the stored password, and re-runs detection against the saved credentials. If it finds a different version than the one stored, it updates the stored one.

On success the dashboard shows Connection OK — API version v14_0 and stamps the last-verified time (shown in your browser’s local time).

Test checks the saved login, so it is disabled while the form has unsaved changes (“Test checks the saved login: save your changes first”). Save & detect first, then test.

A failed test is reported inside a success

The test endpoint answers HTTP 200 even when the test fails, carrying { "ok": false, "error": "..." } in the body. The dashboard reads the ok field and renders Test failed: …, so the UI is correct — but anything calling the API directly must inspect ok rather than the status code.

Rotating the SmartZone password

Change it in SmartZone, then paste the new password into the dashboard and save. The cached service ticket is flushed on every save, so the next call mints a fresh one with the new password — you do not need to reconnect Claude.

Deleting

Delete removes the stored credentials and flushes the cached ticket. Every Claude connector in the organisation stays registered but stops working: call returns no_credentials with the message “No SmartZone controller is saved for this organisation. An admin can save one on the dashboard.”

To revoke Claude’s access rather than the controller’s, see Connecting to Claude.

Error codes on save and test

A failed save reads Not saved: <code>: <detail>; a failed test reads Test failed: <code> — <detail>.

Code	Meaning
forbidden_host	The host is not publicly routable, resolves to a private address, does not resolve at all, or is a tunnel hostname that is not your organisation’s — see Controller requirements
forbidden_port	The port is not 8443 or 443: port <n> is not allowed; use 8443 or 443
invalid_host	The controller could not be reached: refused connection, a timeout after 15 seconds, or a TLS certificate that failed validation
not_smartzone	Something answered, but not as a SmartZone: no SmartZone API at https://<host>:<port>/wsg/api/public/apiInfo (http_<status>). Usually the wrong host or port. No login was sent
login_failed	The controller answered but rejected the login. Carries the upstream status, for example http_401
password_required	The host or port changed and no password was entered
tunnel_down	Controller tunnel only: no cloudflared is connected to the tunnel: start it next to the controller
tunnel_origin_unreachable	Controller tunnel only: cloudflared is running but cannot reach the controller at the LAN address the tunnel names
tunnel_access_denied	Controller tunnel only: Cloudflare Access refused the tunnel's service token
no_credentials	Nothing is saved for this organisation yet
decryption_failed	The stored ciphertext could not be decrypted. Re-enter the password
invalid_body	A field failed validation, for example a host with a scheme or path
unknown	An unexpected error; the detail carries its message

If Save & detect keeps failing with a username and password you know are right, the error is invalid_host, not login_failed: SZ-MCP never reached the login. The usual cause is the controller’s self-signed TLS certificate. See Controller requirements.

The detail returned for login_failed is deliberately terse. SmartZone’s own error bodies can disclose account-lockout state and username hints, so only the status code is kept: the body is neither logged nor echoed back.

Next steps

Connecting to Claude Add the connector, and manage the OAuth tokens that bind it to your account.

Controller requirements The certificate and addressing rules a save has to satisfy.

Security model How the password is encrypted, and when it is decrypted.

Troubleshooting Working back from an error code to the layer that produced it.