Grants

Grants represent active access privileges linking a principal to an asset on a specific platform. They are discovered by connectors during periodic snapshots.

---

Grant Schema

Field	Type	Description
id	UUID	Verity-assigned unique identifier.
principal_id	UUID	The principal who holds this grant.
asset_id	UUID	The asset this grant provides access to.
platform	string	Source platform (e.g. snowflake, fabric, databricks).
privilege	enum	READ · WRITE · EXECUTE · ADMIN
grant_mechanism	enum	How the grant was assigned: direct · group · role · policy
granted_via	string	Role name, group name, or policy that conveyed the privilege (nullable).
granted_at	datetime	When the grant was first observed or assigned.
granted_by_id	UUID	Verity ID of the principal who created the grant (nullable).
is_active	boolean	Whether the grant is currently active.
revoked_at	datetime	When the grant was revoked (nullable).
revoked_by_id	UUID	Verity ID of the principal who revoked the grant (nullable).
snapshot_at	datetime	Timestamp of the last connector snapshot that confirmed this grant.
metadata	object	Connector-specific key-value data.

---

List Grants

GET /v1/grants

Retrieve a paginated list of access grants with optional filters.

Query Parameters

Parameter	Type	Default	Description
principal_id	UUID	—	Filter grants for a specific principal.
asset_id	UUID	—	Filter grants on a specific asset.
platform	string	—	Filter by source platform.
privilege	string	—	Filter by privilege level: READ, WRITE, EXECUTE, ADMIN.
score_lt	float	—	Only return grants whose current decay score is below this threshold (0–100). Useful for finding stale access.
cursor	string	—	Pagination cursor from a previous response.
limit	integer	50	Items per page (max 100).

Example Request

curl -s "http://localhost:8000/v1/grants?platform=snowflake&privilege=READ&score_lt=20&limit=3" \
  -H "Authorization: Bearer $TOKEN"

Example Response

{
  "items": [
    {
      "id": "019f2c3d-4e5f-7000-8000-000000000010",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "platform": "snowflake",
      "privilege": "READ",
      "grant_mechanism": "role",
      "granted_via": "ANALYST_ROLE",
      "granted_at": "2024-01-15T10:00:00Z",
      "granted_by_id": null,
      "is_active": true,
      "revoked_at": null,
      "revoked_by_id": null,
      "snapshot_at": "2025-07-14T06:00:00Z",
      "metadata": {}
    },
    {
      "id": "019f2c3d-4e5f-7000-8000-000000000020",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000002",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000101",
      "platform": "snowflake",
      "privilege": "READ",
      "grant_mechanism": "group",
      "granted_via": "DATA_CONSUMERS",
      "granted_at": "2023-11-20T08:00:00Z",
      "granted_by_id": null,
      "is_active": true,
      "revoked_at": null,
      "revoked_by_id": null,
      "snapshot_at": "2025-07-14T06:00:00Z",
      "metadata": {}
    },
    {
      "id": "019f2c3d-4e5f-7000-8000-000000000030",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000005",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "platform": "snowflake",
      "privilege": "READ",
      "grant_mechanism": "policy",
      "granted_via": "MASKING_POLICY_V2",
      "granted_at": "2024-03-01T12:00:00Z",
      "granted_by_id": "019f1a2b-3c4d-7000-8000-000000000099",
      "is_active": true,
      "revoked_at": null,
      "revoked_by_id": null,
      "snapshot_at": "2025-07-14T06:00:00Z",
      "metadata": {}
    }
  ],
  "next_cursor": "eyJpZCI6IjAxOWYyYzNkLTRlNWYtNzAwMC04MDAwLTAwMDAwMDAwMDA0MCJ9"
}

---

Finding Stale Access

Use the score_lt parameter to identify grants with low decay scores — access that is likely unused and a candidate for revocation:

# Find all grants with a decay score below 15 (very stale)
curl -s "http://localhost:8000/v1/grants?score_lt=15&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Combine with principal_id or asset_id to scope the search:

# Stale grants for a specific principal
curl -s "http://localhost:8000/v1/grants?principal_id=019f1a2b-3c4d-7000-8000-000000000002&score_lt=25" \
  -H "Authorization: Bearer $TOKEN"