`PUT /api/v1/users/:id/scope` — set which node groups an account may see. Limit an account to a set of node groups, or restore fleet-wide visibility with `"All"`.

PUT

/api/v1/users/{id}/scope

curl --request PUT \
  --url https://example.com/api/v1/users/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/scope \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "scope": "All" }'

A scope narrows what the account can see: node lists, aggregates and rankings are filtered to the allowed groups and everything beneath them, and a node outside it answers 404 — the same answer an unknown id gets, so the scope cannot be used to probe for what exists. Endpoints whose answer retains no per-node attribution (a rendered report, a pre-summed fleet timeline) refuse a scoped caller rather than quietly serving fleet-wide numbers.

It is not a substitute for a role: a scoped Operator can still acknowledge alerts and open maintenance windows, within their groups. An Admin cannot be scoped — administration is fleet-wide, so promoting an account to Admin also clears whatever scope it held.

Authorizations

• bearer

Parameters

Path Parameters

id

required

string format: uuid

User account id

Request Body^required

Media typeapplication/json

Change-scope request body.

object

scope

required

One of:

string

Unrestricted visibility.

string

Allowed values: All

object

Visibility limited to these group identifiers.

object

Groups

required

Visibility limited to these group identifiers.

Array<string>

unique items

Responses

204

Scope changed and the account’s sessions revoked

400

The scope names no groups, or names something that is not an existing group id

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role below Admin

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

No such account

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

Refused: the account is an Admin, whose permissions are fleet-wide

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

This core has no write side (skeleton mode)

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}