Scores

The Decay Engine continuously computes a decay score (0–100) for every principal–asset grant pair. A score of 100 indicates active, justified access; a score near 0 indicates stale, likely-unnecessary access.

---

AccessScore Schema

Field	Type	Description
id	UUID	Score record identifier.
principal_id	UUID	The principal this score applies to.
asset_id	UUID	The asset this score applies to.
score	float	Composite decay score (0–100).
component_json	object	Breakdown of individual scoring factors (see below).
trigger	enum	What triggered this score computation: scheduled · event · manual
computed_at	datetime	When this score was computed.
created_at	datetime	Record creation timestamp.

Component Breakdown

The component_json object contains the individual factors that contribute to the composite score:

Component	Range	Description
f_recency	0–1	How recently the access was used (exponential decay).
f_trend	0–1	Usage trend over the trailing window.
f_org	0–1	Organisational alignment (department, role).
f_peer	0–1	Peer-group comparison factor.
f_review	0–1	Boost from recent reviewer confirmation.
sensitivity_mult	0.5–2.0	Multiplier based on asset sensitivity classification.
days_inactive	integer	Days since the principal last accessed this asset.

---

Get Current Score

GET /v1/scores/{principal_id}/{asset_id}

Retrieve the most recent decay score for a principal–asset pair.

Path Parameters

Parameter	Type	Description
principal_id	UUID	The principal's Verity UUID.
asset_id	UUID	The asset's Verity UUID.

Example Request

curl -s "http://localhost:8000/v1/scores/019f1a2b-3c4d-7000-8000-000000000001/019f3d4e-5f60-7000-8000-000000000100" \
  -H "Authorization: Bearer $TOKEN"

Example Response

{
  "id": "019f5a6b-7c8d-7000-8000-000000005001",
  "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
  "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
  "score": 72.4,
  "component_json": {
    "f_recency": 0.85,
    "f_trend": 0.70,
    "f_org": 0.90,
    "f_peer": 0.65,
    "f_review": 1.00,
    "sensitivity_mult": 1.5,
    "days_inactive": 1
  },
  "trigger": "scheduled",
  "computed_at": "2025-07-14T06:00:00Z",
  "created_at": "2025-07-14T06:00:00Z"
}

Error Responses

Status	Description
404	No score found for this principal–asset combination.

---

Score History

GET /v1/scores/{principal_id}/{asset_id}/history

Retrieve a time series of decay scores for a principal–asset pair. Useful for dashboards and trend analysis.

Path Parameters

Parameter	Type	Description
principal_id	UUID	The principal's Verity UUID.
asset_id	UUID	The asset's Verity UUID.

Query Parameters

Parameter	Type	Default	Description
start	datetime	30 days ago	Start of the time range (ISO 8601).
end	datetime	now	End of the time range (ISO 8601).
cursor	string	—	Pagination cursor.
limit	integer	50	Items per page (max 100).

Example Request

curl -s "http://localhost:8000/v1/scores/019f1a2b-3c4d-7000-8000-000000000001/019f3d4e-5f60-7000-8000-000000000100/history?start=2025-06-01T00:00:00Z&end=2025-07-14T23:59:59Z&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Example Response

{
  "items": [
    {
      "id": "019f5a6b-7c8d-7000-8000-000000005001",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "score": 72.4,
      "component_json": {
        "f_recency": 0.85,
        "f_trend": 0.70,
        "f_org": 0.90,
        "f_peer": 0.65,
        "f_review": 1.00,
        "sensitivity_mult": 1.5,
        "days_inactive": 1
      },
      "trigger": "scheduled",
      "computed_at": "2025-07-14T06:00:00Z",
      "created_at": "2025-07-14T06:00:00Z"
    },
    {
      "id": "019f5a6b-7c8d-7000-8000-000000004901",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "score": 68.1,
      "component_json": {
        "f_recency": 0.78,
        "f_trend": 0.65,
        "f_org": 0.90,
        "f_peer": 0.62,
        "f_review": 1.00,
        "sensitivity_mult": 1.5,
        "days_inactive": 3
      },
      "trigger": "scheduled",
      "computed_at": "2025-07-11T06:00:00Z",
      "created_at": "2025-07-11T06:00:00Z"
    },
    {
      "id": "019f5a6b-7c8d-7000-8000-000000004801",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "score": 81.7,
      "component_json": {
        "f_recency": 0.95,
        "f_trend": 0.80,
        "f_org": 0.90,
        "f_peer": 0.68,
        "f_review": 1.00,
        "sensitivity_mult": 1.5,
        "days_inactive": 0
      },
      "trigger": "event",
      "computed_at": "2025-07-08T14:30:00Z",
      "created_at": "2025-07-08T14:30:00Z"
    },
    {
      "id": "019f5a6b-7c8d-7000-8000-000000004701",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "score": 55.3,
      "component_json": {
        "f_recency": 0.55,
        "f_trend": 0.50,
        "f_org": 0.90,
        "f_peer": 0.60,
        "f_review": 0.80,
        "sensitivity_mult": 1.5,
        "days_inactive": 12
      },
      "trigger": "scheduled",
      "computed_at": "2025-06-26T06:00:00Z",
      "created_at": "2025-06-26T06:00:00Z"
    },
    {
      "id": "019f5a6b-7c8d-7000-8000-000000004601",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "score": 42.0,
      "component_json": {
        "f_recency": 0.35,
        "f_trend": 0.40,
        "f_org": 0.90,
        "f_peer": 0.55,
        "f_review": 0.80,
        "sensitivity_mult": 1.5,
        "days_inactive": 24
      },
      "trigger": "scheduled",
      "computed_at": "2025-06-14T06:00:00Z",
      "created_at": "2025-06-14T06:00:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6IjAxOWY1YTZiLTdjOGQtNzAwMC04MDAwLTAwMDAwMDAwNDUwMSJ9"
}

Interpreting score trends

A declining score over time indicates the principal is using the asset less frequently. When the score drops below your organisation's threshold (commonly 30), the Review Generator creates a review packet for human decision.