Security & Compliance API Reference

On this page

Audit logging, security reviews, data archiving, and control mapping against NIST SP 800-53 (the federal security-control catalog).

Endpoints

Admin Units

/v1/security/admin/units

GET /v1/security/admin/units

Table 1. Parameters
Name In Required Description

jurisdiction

query

No

Jurisdiction

unit_type

query

No

Unit type

search

query

No

Full-text search across name, fips_code.

sort_by

query

No

Sort column: name, unit_type, jurisdiction, fips_code.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated admin units

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/admin/units

POST /v1/security/admin/units

Table 2. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1261) — REQUIRED. Same id + identical intent replays the original admin unit; a different intent under the same id is a 409 idempotency-conflict.

fips_code

string (optional)

No

Optional FIPS code for the unit.

jurisdiction

string

Yes

Jurisdiction the unit is scoped to.

name

string

Yes

Display name of the administrative unit.

state_fips

string

Yes

State FIPS code the unit belongs to.

unit_type

string

Yes

Unit type (e.g. county, region).
Responses

  • 200: Admin unit created (or replayed — same client_request_id + intent)

  • 409: Duplicate name+jurisdiction, client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/admin/units/{id}

GET /v1/security/admin/units/{id}

Table 3. Parameters
Name In Required Description

id

path

Yes

Admin unit ID
Responses

  • 200: Admin unit

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/admin/units/{id}

PUT /v1/security/admin/units/{id}

Table 4. Parameters
Name In Required Description

id

path

Yes

Admin unit ID

If-Match

header

Yes

REQUIRED row version from your last read (ADR-062 §G3), e.g. "3" or 3
Table 5. Request Fields
Field Type Required Description

fips_code

string (optional)

No

Optional FIPS code for the unit.

name

string

Yes

Display name of the administrative unit.

state_fips

string

Yes

State FIPS code the unit belongs to.

unit_type

string

Yes

Unit type (e.g. county, region).
Responses

  • 200: Admin unit updated

  • 400: Missing or malformed If-Match

  • 404: Not found

  • 409: Version moved since your read (stale If-Match) — re-read and retry

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/admin/units/{id}

DELETE /v1/security/admin/units/{id}

Table 6. Parameters
Name In Required Description

id

path

Yes

Admin unit ID
Responses

  • 200: Admin unit soft-deleted

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Alerts

/v1/security/alerts

GET /v1/security/alerts

Table 7. Parameters
Name In Required Description

severity

query

No

Severity

acknowledged

query

No

Acknowledged

search

query

No

Full-text search across rule_name, description.

sort_by

query

No

Sort column: severity, rule_name, acknowledged, created_at.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated alerts

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/alerts/{id}

GET /v1/security/alerts/{id}

Table 8. Parameters
Name In Required Description

id

path

Yes

Alert ID
Responses

  • 200: Alert found

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/alerts/{id}/acknowledge

PUT /v1/security/alerts/{id}/acknowledge

Table 9. Parameters
Name In Required Description

id

path

Yes

Alert ID
Responses

  • 200: Alert acknowledged

  • 404: Not found or already acknowledged

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Archive

/v1/security/archive

GET /v1/security/archive

Table 10. Parameters
Name In Required Description

source_service

query

No

Source service

search

query

No

Full-text search across source_service, source_table.

sort_by

query

No

Sort column: source_service, source_table, retention_until, archived_at.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated archive records

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/archive/purge

POST /v1/security/archive/purge

Table 11. Parameters
Name In Required Description

limit

query

No

Rows per call, 1..=100 (D12). Default 100.
Responses

  • 200: Bounded purge: counts + a more flag

  • 403: Archiver disabled (D11 consent knob)

  • 409: An archive pass is running

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/archive/run

POST /v1/security/archive/run

Responses

  • 200: One bounded archive pass: per-table reports + a more flag

  • 403: Archiver disabled (D11 consent knob)

  • 409: A pass is already running

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Audit

/v1/security/audit

GET /v1/security/audit

Table 12. Parameters
Name In Required Description

user_id

query

No

User id

service

query

No

Service

action

query

No

Action

resource_type

query

No

Resource type

resource_id

query

No

Resource id

from

query

No

From

to

query

No

To

actor_service

query

No

Plan E § Step 11: filter by caller-service attribution (e.g. craig-web for BFF-originated audit rows).

actor_user_sub

query

No

Plan E § Step 11: filter by acting-worker normalized UUID sub.

search

query

No

Full-text search across action, user_id.

sort_by

query

No

Sort column: timestamp, action, user_id, service, resource_type, actor_service, actor_user_sub.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated audit log

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/audit/resource/{resource_type}/{resource_id}

GET /v1/security/audit/resource/{resource_type}/{resource_id}

Table 13. Parameters
Name In Required Description

resource_type

path

Yes

Resource type

resource_id

path

Yes

Resource ID
Responses

  • 200: Audit entries for resource

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/audit/user/{user_id}

GET /v1/security/audit/user/{user_id}

Table 14. Parameters
Name In Required Description

user_id

path

Yes

User ID
Responses

  • 200: Audit entries for user

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Config

/v1/security/admin/config

GET /v1/security/admin/config

Responses

  • 200: Deployment configuration

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Detection Rules

/v1/security/detection-rules

GET /v1/security/detection-rules

Responses

  • 200: List of detection rules

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/detection-rules

POST /v1/security/detection-rules

Table 15. Request Fields
Field Type Required Description

business_end_hour

integer (optional)

No

#1143: business-hours band end (0..=23, exclusive-of-after-hours upper bound — 17 means "17:00-17:59 is still business").

business_start_hour

integer (optional)

No

#1143: business-hours band start (0..=23), meaningful for after_hours_access rules — hours are classified in the jurisdiction’s business timezone. Both-or-neither with business_end_hour; start < end (DB CHECK-backed).

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1261) — REQUIRED. Same id + identical intent replays the original detection rule; a different intent under the same id is a 409 idempotency-conflict.

description

string

Yes

What the rule detects.

notify_webhook

string (optional)

No

Optional webhook URL to notify on trigger.

rule_name

string

Yes

Human-readable rule name.

rule_type

string

Yes

Rule category (e.g. rate, anomaly).

severity

string

Yes

Alert severity (e.g. low, high).

threshold

integer

Yes

Trigger threshold (event count).

window_minutes

integer

Yes

Evaluation window in minutes.
Responses

  • 200: Rule created (or replayed — same client_request_id + intent)

  • 400: Invalid rule_type or severity

  • 409: Duplicate rule_name, client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/detection-rules/{id}

PUT /v1/security/detection-rules/{id}

Table 16. Parameters
Name In Required Description

id

path

Yes

Detection rule ID

If-Match

header

Yes

REQUIRED row version from your last read (ADR-062 §G3), e.g. "3" or 3
Table 17. Request Fields
Field Type Required Description

business_end_hour

integer (optional)

No

#1143: new business-hours band end (absent = keep).

business_start_hour

integer (optional)

No

#1143: new business-hours band start (absent = keep). Plain Option — the columns are pair-NULLable but "clear the band" is not a supported operation (a clear would silence the rule; set both hours instead).

enabled

boolean (optional)

No

Enable/disable the rule.

notify_webhook

string (optional)

No

Webhook URL — omitted keeps, explicit null clears, a URL sets (#1356: craig_validation::double_option makes the clear arm wire-reachable; the skip_serializing_if pairing is LOAD-BEARING — flip both together, never one).

severity

string (optional)

No

New alert severity.

threshold

integer (optional)

No

New trigger threshold.

window_minutes

integer (optional)

No

New evaluation window in minutes.
Responses

  • 200: Rule updated

  • 400: Invalid severity, or a missing/malformed If-Match

  • 404: Not found

  • 409: Version moved since your read (stale If-Match) — re-read and retry

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/detection-rules/{id}

DELETE /v1/security/detection-rules/{id}

Table 18. Parameters
Name In Required Description

id

path

Yes

Detection rule ID
Responses

  • 204: Rule deleted

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/detection/run

POST /v1/security/detection/run

Responses

  • 200: Detection scan completed

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Major Changes

/v1/security/changes

GET /v1/security/changes

Table 19. Parameters
Name In Required Description

change_type

query

No

Change type

search

query

No

Full-text search across description, affected_scope.

sort_by

query

No

Sort column: change_type, description, affected_scope, effective_date, reported_to_acf, created_at.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated major changes

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/changes

POST /v1/security/changes

Table 20. Request Fields
Field Type Required Description

affected_scope

string

Yes

Scope of systems/processes affected.

change_type

string

Yes

Category of the change (e.g. system, policy).

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1261) — REQUIRED. Same id + identical intent replays the original major change; a different intent under the same id is a 409 idempotency-conflict.

description

string

Yes

What changed.

effective_date

date

Yes

Date the change takes effect.

notes

string (optional)

No

Optional free-text notes.
Responses

  • 200: Major change recorded (or replayed — same client_request_id + intent)

  • 400: Invalid change_type

  • 409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/changes/{id}

GET /v1/security/changes/{id}

Table 21. Parameters
Name In Required Description

id

path

Yes

Major change ID
Responses

  • 200: Major change found

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/changes/{id}

PUT /v1/security/changes/{id}

Table 22. Parameters
Name In Required Description

id

path

Yes

Major change ID
Table 23. Request Fields
Field Type Required Description

description

string (optional)

No

Updated description.

notes

string (optional)

No

Free-text notes — same keep/clear/set wire contract as reported_date (#1356).

reported_date

date (optional)

No

Date reported to ACF — omitted keeps, explicit null clears, a date sets (#1356: craig_validation::double_option makes the clear arm wire-reachable; the skip_serializing_if pairing is LOAD-BEARING — flip both together, never one).

reported_to_acf

boolean (optional)

No

Whether the change was reported to ACF.
Responses

  • 200: Major change updated

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/changes/{id}

DELETE /v1/security/changes/{id}

Table 24. Parameters
Name In Required Description

id

path

Yes

Major change ID
Responses

  • 204: Major change deleted

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

NIST

/v1/security/nist

GET /v1/security/nist

Table 25. Parameters
Name In Required Description

control_family

query

No

Control family

implementation_status

query

No

Implementation status

search

query

No

Full-text search across control_id, control_family.

sort_by

query

No

Sort column: control_id, control_family, control_name, implementation_status.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated NIST controls

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/nist

POST /v1/security/nist

Table 26. Request Fields
Field Type Required Description

assessed_by

string (optional)

No

Who performed the assessment.

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1261) — REQUIRED. Same id + identical intent replays the original NIST control; a different intent under the same id is a 409 idempotency-conflict.

control_family

string

Yes

Control family (e.g. Access Control).

control_id

string

Yes

Control identifier (e.g. AC-2).

control_name

string

Yes

Human-readable control name.

evidence_key

string (optional)

No

Object-store key for supporting evidence.

implementation_notes

string (optional)

No

Free-text implementation notes.

implementation_status

string (optional)

No

Implementation status (e.g. implemented, planned).

last_assessed

date (optional)

No

Date the control was last assessed.
Responses

  • 200: Control created (or replayed — same client_request_id + intent)

  • 409: Duplicate control_id, client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/nist/{control_id}

GET /v1/security/nist/{control_id}

Table 27. Parameters
Name In Required Description

control_id

path

Yes

NIST control ID (e.g. AC-2)
Responses

  • 200: Control found

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/nist/{control_id}

PUT /v1/security/nist/{control_id}

Table 28. Parameters
Name In Required Description

control_id

path

Yes

NIST control ID (e.g. AC-2)
Table 29. Request Fields
Field Type Required Description

assessed_by

string (optional)

No

Who performed the assessment.

evidence_key

string (optional)

No

Object-store key for supporting evidence.

implementation_notes

string (optional)

No

Free-text implementation notes.

implementation_status

string

Yes

New implementation status.

last_assessed

date (optional)

No

Date the control was last assessed.
Responses

  • 200: Control updated

  • 404: Not found (including a soft-deleted control — previously a 500)

  • 409: Implementation status moved concurrently since your read — re-read and retry (ADR-062 §G3)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/nist/{control_id}

DELETE /v1/security/nist/{control_id}

Table 30. Parameters
Name In Required Description

control_id

path

Yes

NIST control ID (e.g. AC-2)
Responses

  • 204: Control deleted

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Partner Signer Keys

/v1/security/partners/{id}/signer-keys

GET /v1/security/partners/{id}/signer-keys

Table 31. Parameters
Name In Required Description

id

path

Yes

Partner ID
Responses

  • 200: Signer keys for partner

  • 404: Partner not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}/signer-keys

POST /v1/security/partners/{id}/signer-keys

Table 32. Parameters
Name In Required Description

id

path

Yes

Partner ID
Table 33. Request Fields
Field Type Required Description

algorithm

string (optional)

No

Signing algorithm (defaults to ES256 if omitted).

display_name

string

Yes

Human-readable display name, e.g. "Dr. Jones".

expires_at

datetime (optional)

No

Optional key expiry.

key_id

string

Yes

kid in the JWS header; globally unique.

public_key_jwk

object

Yes

Public key as a JWK (RFC 7517).

user_identifier

string

Yes

Partner-scoped identifier for the signing person (email, employee id).
Responses

  • 200: Signer key registered (pending admin approval)

  • 400: Invalid algorithm

  • 404: Partner not found

  • 409: Duplicate kid

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}/signer-keys/{signer_key_id}/approve

PUT /v1/security/partners/{id}/signer-keys/{signer_key_id}/approve

Table 34. Parameters
Name In Required Description

id

path

Yes

Partner ID

signer_key_id

path

Yes

Signer key ID
Responses

  • 200: Approved

  • 404: Not found or already approved

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}/signer-keys/{signer_key_id}/revoke

PUT /v1/security/partners/{id}/signer-keys/{signer_key_id}/revoke

Table 35. Parameters
Name In Required Description

id

path

Yes

Partner ID

signer_key_id

path

Yes

Signer key ID
Responses

  • 200: Revoked

  • 404: Not found or already revoked

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/signer-keys/by-kid/{kid}

GET /v1/security/signer-keys/by-kid/{kid}

Table 36. Parameters
Name In Required Description

kid

path

Yes

JWS kid header value
Responses

  • 200: Signer key metadata + pubkey

  • 404: Unknown/pending/revoked kid or inactive partner

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Partners

/v1/security/partners

GET /v1/security/partners

Table 37. Parameters
Name In Required Description

kind

query

No

Kind

status

query

No

Status

search

query

No

Full-text search across name, contact_email.

sort_by

query

No

Sort column: name, kind, status, created_at.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated partners

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners

POST /v1/security/partners

Table 38. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1261) — REQUIRED. Same id + identical intent replays the original partner; a different intent under the same id is a 409 idempotency-conflict.

contact_email

string (optional)

No

Contact email (capped at SHORT_TEXT_MAX to cover the RFC-5321 practical ceiling).

contact_phone

string (optional)

No

Contact phone.

kind

string

Yes

Partner kind. One of: hospital, school, le, other.

name

string

Yes

Partner display name.

rate_limit_rpm

integer (optional)

No

Per-minute rate limit (defaults to 60 if omitted).
Responses

  • 200: Partner created (or replayed — same client_request_id + intent)

  • 400: Invalid kind

  • 409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/verify

POST /v1/security/partners/verify

Table 39. Request Fields
Field Type Required Description

api_key

string

Yes

Raw API key — intake forwards the partner-presented credential here.
Responses

  • 200: Credential valid

  • 401: Credential invalid, revoked, or partner suspended

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}

GET /v1/security/partners/{id}

Table 40. Parameters
Name In Required Description

id

path

Yes

Partner ID
Responses

  • 200: Partner found

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}

PUT /v1/security/partners/{id}

Table 41. Parameters
Name In Required Description

id

path

Yes

Partner ID
Table 42. Request Fields
Field Type Required Description

contact_email

string (optional)

No

Contact email — omitted keeps, explicit null clears, a string sets (#1356: craig_validation::double_option makes the clear arm wire-reachable; the skip_serializing_if pairing is LOAD-BEARING — without it a Rust-side keep-intent None would serialize as null, which the fixed deserializer reads as CLEAR: unintended data loss. Flip both attributes together, never one).

contact_phone

string (optional)

No

Contact phone — same keep/clear/set wire contract as contact_email (#1356).

name

string (optional)

No

New partner display name.

rate_limit_rpm

integer (optional)

No

Per-minute rate limit.

status

string (optional)

No

Status transition: active ↔ suspended (use DELETE for soft-delete).

version

integer

Yes

REQUIRED row version from your last read (ADR-062 §G3, #1268) — the version CAS. Suspension cycles are ABA-vulnerable, so only the monotonic counter blocks a stale re-suspension replay; stale → 409 concurrent-modification.
Responses

  • 200: Partner updated

  • 404: Not found

  • 409: Version moved since your read (stale body version) — re-read and retry (ADR-062 §G3)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}

DELETE /v1/security/partners/{id}

Table 43. Parameters
Name In Required Description

id

path

Yes

Partner ID
Responses

  • 200: Partner soft-deleted

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}/keys

GET /v1/security/partners/{id}/keys

Table 44. Parameters
Name In Required Description

id

path

Yes

Partner ID
Responses

  • 200: Keys for partner (hash/prefix only)

  • 404: Partner not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}/keys

POST /v1/security/partners/{id}/keys

Table 45. Parameters
Name In Required Description

id

path

Yes

Partner ID
Table 46. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1262) — REQUIRED. One-time-secret contract: the plaintext key is returned exactly once, so a replay under the same id + intent is a 409 one-time-secret-already-issued naming the existing key id — never a 200 and never the secret again.

expires_at

datetime (optional)

No

Override the default 1-year expiry.

label

string (optional)

No

Operator-facing label (optional).
Responses

  • 200: Key issued; plaintext returned once — a replay never re-exposes it

  • 404: Partner not found (including soft-deleted)

  • 409: One-time secret already issued for this client_request_id (naming the key id, never the secret), the id is claimed by a different operation (ADR-062), or the partner is suspended (partner-not-active, #1290 — re-activate and retry; the refusal consumed nothing)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/partners/{id}/keys/{key_id}

DELETE /v1/security/partners/{id}/keys/{key_id}

Table 47. Parameters
Name In Required Description

id

path

Yes

Partner ID

key_id

path

Yes

Key ID
Responses

  • 200: Key revoked

  • 404: Key not found or already revoked

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Plan C § Step 7 (F-009): rotation. Atomically revokes the named key and

issues a new one belonging to the same partner. Returns the new row
raw plaintext (one-time view, same contract as issue_key). #1262: takes rotation’s first body — the 1-field claim id — and replays 409 naming the previously rotated-in key, never re-exposing its plaintext.

POST /v1/security/partners/{id}/keys/{key_id}/rotate

Table 48. Parameters
Name In Required Description

id

path

Yes

Partner ID

key_id

path

Yes

Key ID being rotated
Table 49. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1262) — REQUIRED. Same one-time-secret replay contract as IssueKeyRequest: a replay 409s naming the key already issued by the original rotation, never re-exposing its plaintext.
Responses

  • 200: Rotated; new plaintext key returned once — a replay never re-exposes it

  • 404: Key not found or already revoked, or the partner is soft-deleted (#1290 masking)

  • 409: One-time secret already issued for this client_request_id (naming the new key id, never the secret), the id is claimed by a different operation (ADR-062), or the partner is suspended (partner-not-active, #1290 — re-activate and retry; the refusal consumed nothing)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Reviews

/v1/security/reviews

GET /v1/security/reviews

Table 50. Parameters
Name In Required Description

review_type

query

No

Review type

status

query

No

Status

search

query

No

Full-text search across review_type.

sort_by

query

No

Sort column: review_type, status, scheduled_date, reviewer.

sort_dir

query

No

Sort direction: asc or desc (default: desc).

page

query

No

Page

per_page

query

No

Per page
Responses

  • 200: Paginated reviews

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/reviews

POST /v1/security/reviews

Table 51. Request Fields
Field Type Required Description

client_request_id

UUID

Yes

Client-minted idempotency id (ADR-062 §B, #1261) — REQUIRED. Same id + identical intent replays the original review; a different intent under the same id is a 409 idempotency-conflict.

review_type

string

Yes

Review category — the closed craig_reference::ReviewType vocabulary (biennial, incident, ad_hoc, access_review); anything else is refused with the typed 400 INVALID_ENUM_VALUE (#1288). Wire type stays String (the contract crate carries no reference-enum dependency); the service parses against the canonical enum.

reviewer

string

Yes

Name of the assigned reviewer.

scheduled_date

date

Yes

Date the review is scheduled for.
Responses

  • 200: Review created (or replayed — same client_request_id + intent)

  • 400: Invalid review_type — outside the canonical ReviewType vocabulary (#1288)

  • 409: client_request_id claimed by a different operation, or replayed entity gone (ADR-062)

  • 422: Validation failure (including a missing client_request_id)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/reviews/{id}

GET /v1/security/reviews/{id}

Table 52. Parameters
Name In Required Description

id

path

Yes

Review ID
Responses

  • 200: Review found

  • 404: Not found

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/reviews/{id}

PUT /v1/security/reviews/{id}

Table 53. Parameters
Name In Required Description

id

path

Yes

Review ID
Table 54. Request Fields
Field Type Required Description

completed_date

date (optional)

No

Date the review was completed.

findings

object

No

Structured findings payload (stored as-is).

remediation_plan

object

No

Structured remediation-plan payload (stored as-is).

status

string

Yes

New review status.
Responses

  • 200: Review updated

  • 404: Not found (including a soft-deleted review — previously still mutable)

  • 409: Status moved concurrently since your read — re-read and retry (ADR-062 §G3)

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

/v1/security/reviews/{id}

DELETE /v1/security/reviews/{id}

Table 55. Parameters
Name In Required Description

id

path

Yes

Review ID
Responses

  • 204: Review deleted

  • 404: Not found

  • 409: Review has attached evidence

  • 500: Internal error

  • 503: Service Unavailable (RFC 9457 problem document, ADR-068): database pool exhaustion (carries Retry-After: 5), db-connection-lost, db-outcome-unknown, or a synchronous upstream dependency refusal.

  • 504: Gateway Timeout (RFC 9457 problem document, ADR-068): the route-class request ceiling elapsed (request-timeout) or the database canceled the statement (db-timeout) — the server yields first.

Edit this page · latest