Skip to content

Update public-mode settings

PATCH
/admin/system/public-mode

Turns public mode on or off.

You need system.config.write or system.admin for the whole install; read permission isn’t enough, and a permission held only for a team doesn’t count. A body that can’t be decoded gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

Always send enabled. The schema marks it required, but the server currently reads {}, a JSON null body or a null enabled as false, so those bodies turn public mode off rather than leaving it alone. An empty body, malformed JSON or a wrong field type gets the 400.

The response echoes the value this request saved. Before responding, the server tries to notify the access caches. It doesn’t clear its own cached public-mode value directly, and a failed notification doesn’t fail the save. So later anonymous requests, even on this app instance and after a successful response, can still see the old setting. Cached values don’t expire on a timer, and requests already let through aren’t recalled.

Public mode only decides admission to the paths listed under getPublicMode. It doesn’t replace those handlers’ own access rules or change how callers with a valid identity are admitted. A successful save tries to record an admin.system.public_mode_updated audit event, and an audit failure doesn’t undo the setting.

There’s no version check, so concurrent updates can overwrite each other, and the response shows this request’s value rather than a fresh read of the final setting.

The instance setting that decides whether anonymous requests are admitted to the governed public paths. It’s separate from each handler’s own access rules.

object
enabled
required

True lets requests with no valid identity reach the handlers on the governed public paths. False asks the middleware to refuse them with 401, and is the default until a setting is saved. Requests with a valid identity skip this check. The middleware caches the value, so the saved value isn’t necessarily the one it’s using right now. Other anonymous endpoints keep their own access rules.

boolean

The public-mode value this request saved; the access caches may still be using an older one.

The instance setting that decides whether anonymous requests are admitted to the governed public paths. It’s separate from each handler’s own access rules.

object
enabled
required

True lets requests with no valid identity reach the handlers on the governed public paths. False asks the middleware to refuse them with 401, and is the default until a setting is saved. Requests with a valid identity skip this check. The middleware caches the value, so the saved value isn’t necessarily the one it’s using right now. Other anonymous endpoints keep their own access rules.

boolean

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed