Skip to content
Registry StackDocsLatest
Search

Dry-run a candidate runtime config

POST
/admin/v1/config/dry-run
curl --request POST \
  --url https://example.com/admin/v1/config/dry-run \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <X-Api-Key>' \
  --data '{ "break_glass": false, "break_glass_approval": { "approval_reference": "example", "approved_by": "example", "emergency_change_class": "example", "expires_at_unix_seconds": 1, "rate_limit_identity": "example", "reason": "example" }, "break_glass_approval_reference": "example", "bundle_id": "example", "config_yaml": "example", "local_approval_reference": "example", "previous_config_hash": "example", "root_version": 1, "sequence": 1, "stream_id": "default", "tuf": { "datastore_dir": "example", "metadata_dir": "example", "root_path": "example", "target_name": "example", "targets_dir": "example" } }'

Standalone mode validates an inline candidate config or verifies a local or remote signed TUF config target. Inline candidates and non-swappable changes report rejected_restart_required without mutating runtime state.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
break_glass

Apply-only emergency mode. Verify and dry-run reject break-glass requests.

boolean
break_glass_approval
object
approval_reference
required
string
>= 1 characters
approved_by
required
string
>= 1 characters
emergency_change_class
required

Must appear in the signed target change_classes and be authorized by local trust roots.

string
>= 1 characters
expires_at_unix_seconds
required
integer format: uint64
rate_limit_identity
required
string
>= 1 characters
reason
required

Local approval reason. Audit records store only a hash of this value.

string
>= 1 characters
break_glass_approval_reference

Apply-only reference for a matching durable break-glass approval record in the verifier-owned local approval store.

string
bundle_id

Operator-visible candidate identifier. Signed TUF targets may derive it from target metadata.

string
config_yaml

Inline YAML candidate for verify and dry-run diagnostics.

string
local_approval_reference

Apply-only reference for a matching local approval record used by root_transition bundles.

string
previous_config_hash

Governed predecessor config hash. Requests and signed target metadata may provide either bare lowercase SHA-256 hex or sha256:<64 lowercase hex>; responses, audit, docs, and errors use the canonical sha256:-prefixed form.

string
/^(sha256:)?[0-9a-f]{64}$/
root_version
integer format: uint64
sequence

Monotonic bundle sequence. Signed TUF targets may derive it from target metadata.

integer format: uint64
stream_id

Governance stream identifier used by anti-rollback state.

string
default: default
tuf
One of:
object
datastore_dir
required
string
metadata_dir
required
string
root_path
required
string
target_name
required
string
targets_dir
required
string

Responses

Section titled “Responses”

200

Section titled “200”

Candidate config was evaluated without applying

Media typeapplication/json
object
applied
required
boolean
bundle_id
required
string
detail

Optional diagnostic detail. Previous-config-hash mismatch details use canonical sha256:<64 lowercase hex> for the expected value and name the detected received format.

string
posture_result
required

Posture projection of the outcome, such as accepted, rejected, or not_applied.

string
restart_required
required
boolean
result
required

Config apply outcome, such as applied, verified, rejected_restart_required, rejected_readiness, or rejected_rollback.

string
sequence
required
integer format: uint64
Example
{
  "applied": false,
  "bundle_id": "demo-bundle",
  "posture_result": "rejected",
  "restart_required": true,
  "result": "rejected_restart_required",
  "sequence": 1
}

400

Section titled “400”

Candidate config is invalid

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "config.candidate_invalid",
  "detail": "candidate config could not be parsed",
  "status": 400,
  "title": "Candidate config invalid",
  "type": "https://docs.registry-notary.dev/problems/config/candidate_invalid"
}

401

Section titled “401”

Missing or invalid credential

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.missing_credential",
  "detail": "missing authentication credential",
  "status": 401,
  "title": "Missing credential",
  "type": "https://docs.registry-notary.dev/problems/auth/missing_credential"
}

403

Section titled “403”

Caller lacks registry_notary:admin scope

Media typeapplication/problem+json
object
code
required
string
detail
required
string
request_id
required
string
status
required
integer format: int32
title
required
string
type
required
string format: uri
key
additional properties
any
Example
{
  "code": "auth.scope_denied",
  "detail": "missing required scope",
  "status": 403,
  "title": "Scope denied",
  "type": "https://docs.registry-notary.dev/problems/auth/scope_denied"
}