Skip to content

Verity — Access Decay Intelligence Platform

Principals

Principals¶

Principals represent identities in the Verity system — users, service principals, groups, and applications — ingested from connected platforms.

Principal Schema¶

Field	Type	Description
`id`	UUID	Verity-assigned unique identifier.
`external_id`	string	Original ID from the source platform.
`source`	string	Platform that owns this identity (e.g. `entra_id`, `snowflake`).
`type`	enum	`user` · `service_principal` · `group` · `application`
`display_name`	string	Human-readable name.
`email`	string	Email address (nullable).
`department`	string	Organisational department (nullable).
`job_title`	string	Job title (nullable).
`manager_id`	UUID	Verity ID of the principal's manager (nullable).
`peer_group_id`	UUID	Auto-assigned peer-group cluster (nullable).
`is_active`	boolean	Whether the principal is currently active.
`hired_at`	datetime	Employment start date (nullable).
`terminated_at`	datetime	Employment end date (nullable).
`last_seen_at`	datetime	Last observed activity timestamp.
`metadata`	object	Connector-specific key-value data.
`created_at`	datetime	Record creation timestamp.
`updated_at`	datetime	Record last-updated timestamp.

List Principals¶

GET /v1/principals

Retrieve a paginated list of principals, with optional filters.

Query Parameters¶

Parameter	Type	Default	Description
`type`	string	—	Filter by principal type: `user`, `service_principal`, `group`, `application`.
`active`	boolean	—	Filter by active status (`true` or `false`).
`peer_group_id`	UUID	—	Filter by peer-group cluster ID.
`search`	string	—	Full-text search across `display_name` and `email`.
`cursor`	string	—	Pagination cursor from a previous response.
`limit`	integer	50	Items per page (max 100).

Example Request¶

curl -s "http://localhost:8000/v1/principals?type=user&active=true&limit=2" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

{
  "items": [
    {
      "id": "019f1a2b-3c4d-7000-8000-000000000001",
      "external_id": "alice@contoso.com",
      "source": "entra_id",
      "type": "user",
      "display_name": "Alice Johnson",
      "email": "alice@contoso.com",
      "department": "Engineering",
      "job_title": "Senior Data Engineer",
      "manager_id": "019f1a2b-3c4d-7000-8000-000000000099",
      "peer_group_id": "019f1a2b-3c4d-7000-8000-00000000aa01",
      "is_active": true,
      "hired_at": "2021-03-15T00:00:00Z",
      "terminated_at": null,
      "last_seen_at": "2025-07-14T09:22:11Z",
      "metadata": {
        "entra_object_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-07-14T09:22:11Z"
    },
    {
      "id": "019f1a2b-3c4d-7000-8000-000000000002",
      "external_id": "bob@contoso.com",
      "source": "entra_id",
      "type": "user",
      "display_name": "Bob Martinez",
      "email": "bob@contoso.com",
      "department": "Finance",
      "job_title": "Financial Analyst",
      "manager_id": "019f1a2b-3c4d-7000-8000-000000000098",
      "peer_group_id": "019f1a2b-3c4d-7000-8000-00000000aa02",
      "is_active": true,
      "hired_at": "2022-06-01T00:00:00Z",
      "terminated_at": null,
      "last_seen_at": "2025-07-10T14:05:33Z",
      "metadata": {
        "entra_object_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
      },
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-07-10T14:05:33Z"
    }
  ],
  "next_cursor": "eyJpZCI6IjAxOWYxYTJiLTNjNGQtNzAwMC04MDAwLTAwMDAwMDAwMDAwMyJ9"
}

Get Principal¶

GET /v1/principals/{id}

Retrieve a single principal by its Verity ID.

Path Parameters¶

Parameter	Type	Description
`id`	UUID	The principal's Verity UUID.

Example Request¶

curl -s "http://localhost:8000/v1/principals/019f1a2b-3c4d-7000-8000-000000000001" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

{
  "id": "019f1a2b-3c4d-7000-8000-000000000001",
  "external_id": "alice@contoso.com",
  "source": "entra_id",
  "type": "user",
  "display_name": "Alice Johnson",
  "email": "alice@contoso.com",
  "department": "Engineering",
  "job_title": "Senior Data Engineer",
  "manager_id": "019f1a2b-3c4d-7000-8000-000000000099",
  "peer_group_id": "019f1a2b-3c4d-7000-8000-00000000aa01",
  "is_active": true,
  "hired_at": "2021-03-15T00:00:00Z",
  "terminated_at": null,
  "last_seen_at": "2025-07-14T09:22:11Z",
  "metadata": {
    "entra_object_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "created_at": "2025-01-10T08:00:00Z",
  "updated_at": "2025-07-14T09:22:11Z"
}

Error Responses¶

Status	Description
404	Principal not found.

{
  "detail": "Principal not found"
}

List Grants for a Principal¶

GET /v1/principals/{id}/grants

Retrieve all active access grants assigned to a specific principal.

Path Parameters¶

Parameter	Type	Description
`id`	UUID	The principal's Verity UUID.

Query Parameters¶

Parameter	Type	Default	Description
`cursor`	string	—	Pagination cursor.
`limit`	integer	50	Items per page (max 100).

Example Request¶

curl -s "http://localhost:8000/v1/principals/019f1a2b-3c4d-7000-8000-000000000001/grants?limit=2" \
  -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-000000000011",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000200",
      "platform": "fabric",
      "privilege": "WRITE",
      "grant_mechanism": "direct",
      "granted_via": null,
      "granted_at": "2024-06-20T14:30: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": null
}

List Access Events for a Principal¶

GET /v1/principals/{id}/events

Retrieve recent access events (data-plane activity) observed for a principal.

Path Parameters¶

Parameter	Type	Description
`id`	UUID	The principal's Verity UUID.

Query Parameters¶

Parameter	Type	Default	Description
`cursor`	string	—	Pagination cursor.
`limit`	integer	50	Items per page (max 100).

Example Request¶

curl -s "http://localhost:8000/v1/principals/019f1a2b-3c4d-7000-8000-000000000001/events?limit=2" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

{
  "items": [
    {
      "id": "019f4e5f-6071-7000-8000-000000001001",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000100",
      "platform": "snowflake",
      "action": "SELECT",
      "occurred_at": "2025-07-14T09:22:11Z",
      "row_count": 1500,
      "bytes_scanned": 4096000,
      "metadata": {
        "warehouse": "ANALYTICS_WH",
        "query_id": "01b2c3d4-5e6f-7890-abcd-ef1234500000"
      }
    },
    {
      "id": "019f4e5f-6071-7000-8000-000000001002",
      "principal_id": "019f1a2b-3c4d-7000-8000-000000000001",
      "asset_id": "019f3d4e-5f60-7000-8000-000000000200",
      "platform": "fabric",
      "action": "INSERT",
      "occurred_at": "2025-07-13T16:45:00Z",
      "row_count": 250,
      "bytes_scanned": null,
      "metadata": {}
    }
  ],
  "next_cursor": null
}