Entity Management API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The Entity Management API provides low-level access to the entity index, which tracks all discovered identities, accounts, groups, and their relationships (edges). This API supports creating index stores, querying indexed entities with filtering and pagination, and managing edges between entities.

Source: src/entman/rest/rest.go

Base Path

/internal/v1/entity/index

Authentication

All endpoints require JWT cookie or API token authentication.

Endpoints

Method	Path	Description	Auth required
POST	/internal/v1/entity/index/store	Create a new entity index store	JWT + API token
POST	/internal/v1/entity/index/store/query	Query entity index entries with filtering	JWT + API token
POST	/internal/v1/entity/index/edge/add	Add relationship edges	JWT + API token
POST	/internal/v1/entity/index/edge/del	Delete relationship edges	JWT + API token
POST	/internal/v1/entity/index/entity/add	Add entities to the index	JWT + API token
POST	/internal/v1/entity/index/entity/del	Delete entities from the index	JWT + API token

---

POST /internal/v1/entity/index/store

Create a new entity mapper store. A store represents an indexed view of entities at a specific point in time, used for mapping operations.

Request:

POST /internal/v1/entity/index/store
Content-Type: application/json
Authorization: Bearer <token>

{
  "id": "store-uuid",
  "viewTime": 1707700800000
}

Request fields:

Field	Type	Description
id	string	Store identifier
viewTime	int64	Point-in-time timestamp (ms) for the entity snapshot

Response (200): Returns the created MapperStore with populated replication node metadata.

---

POST /internal/v1/entity/index/store/query

Query entities in the index store with filtering, pagination, and mapping status information.

Request:

POST /internal/v1/entity/index/store/query
Content-Type: application/json
Authorization: Bearer <token>

{
  "id": "store-uuid",
  "type": "identity.user",
  "skip": 0,
  "limit": 100,
  "filter": {
    "search": "john",
    "all": false,
    "isMappedCurrent": true,
    "isMappedOther": false,
    "isUnmapped": false
  },
  "mappedTo": "edge.identity.account",
  "tombstoned": false,
  "classifications": true,
  "mappingRules": false
}

Query fields:

Field	Type	Description
id	string	Store ID to query
type	string	Entity type filter (e.g., identity.user, identity.group)
skip	int64	Number of entries to skip (pagination offset)
limit	int64	Maximum entries to return (default: 100)
filter.search	string	Free-text search across entity fields
filter.all	bool	Return all entities regardless of mapping status
filter.isMappedCurrent	bool	Include entities mapped in the current store
filter.isMappedOther	bool	Include entities mapped in other stores
filter.isUnmapped	bool	Include unmapped entities only
mappedTo	string	Filter by outgoing edge type
mappedFrom	string	Filter by incoming edge type
uniqueId	string	Get a specific entity by unique ID
tombstoned	bool	Include tombstoned (soft-deleted) entries
tombstonedMappings	bool	Include tombstoned mappings
classifications	bool	Include classification data
mappingRules	bool	Include matching mapping rules

Response (200):

{
  "total": 4521,
  "last": 100,
  "mapped": 4200,
  "unmapped": 321,
  "entry": [
    {
      "id": 1,
      "dataSourceId": "ds-uuid",
      "dataSource": "Corporate AD",
      "uniqueId": "acct-uuid",
      "entityType": "identity.user",
      "entitySearch": "john doe jdoe",
      "platform": "Active Directory",
      "entity": { },
      "mapping": [
        {
          "uniqueId": "owner-uuid",
          "edgeType": "edge.identity.account",
          "time": 1707700800000,
          "tombstoned": false
        }
      ],
      "mapped": true,
      "tombstoned": false,
      "time": 1707700800000,
      "mappings": 1
    }
  ]
}

Response fields:

Field	Type	Description
total	int64	Total matching entries
last	int64	Index of the last returned entry
mapped	int64	Count of mapped entries matching the filter
unmapped	int64	Count of unmapped entries matching the filter
entry[].entity	object	The full entity data (deserialized from protobuf)
entry[].mapping	array	Active edge mappings for this entity

---

POST /internal/v1/entity/index/edge/add

Add relationship edges between entities in the index. Edges represent connections like account-to-owner mappings or group memberships.

Request:

POST /internal/v1/entity/index/edge/add
Content-Type: application/json
Authorization: Bearer <token>

{
  "id": "store-uuid",
  "type": "edge.identity.account",
  "edge": [
    { "from": "owner-uuid-1", "to": "account-uuid-1" },
    { "from": "owner-uuid-1", "to": "account-uuid-2" }
  ]
}

Request fields:

Field	Type	Description
id	string	Store ID
type	string	Edge type (e.g., edge.identity.account, edge.identity.manager)
edge[].from	string	Source entity unique ID
edge[].to	string	Target entity unique ID

Response (200): Returns the same EdgeRequest structure confirming the added edges.

---

POST /internal/v1/entity/index/edge/del

Remove relationship edges from the entity index. Uses the same request structure as add edges.

Request:

POST /internal/v1/entity/index/edge/del
Content-Type: application/json
Authorization: Bearer <token>

{
  "id": "store-uuid",
  "type": "edge.identity.account",
  "edge": [
    { "from": "owner-uuid-1", "to": "account-uuid-1" }
  ]
}

Response (200): Returns the EdgeRequest confirming the deleted edges.

---

POST /internal/v1/entity/index/entity/add

Add entities to the index store. Entities are serialized from their protobuf definitions.

Request:

POST /internal/v1/entity/index/entity/add
Content-Type: application/json
Authorization: Bearer <token>

{
  "id": "store-uuid",
  "type": "identity.user",
  "entity": [
    {
      "id": "entity-uuid-1",
      "entity": {
        "displayName": "John Doe",
        "email": "john.doe@company.com"
      }
    }
  ]
}

Request fields:

Field	Type	Description
id	string	Store ID
type	string	Entity type (looked up via protobuf registry)
entity[].id	string	Entity unique ID
entity[].entity	object	Entity data matching the protobuf schema for the type

Response (200): Returns the EntityRequest confirming the added entities.

---

POST /internal/v1/entity/index/entity/del

Remove entities from the index store.

Request:

POST /internal/v1/entity/index/entity/del
Content-Type: application/json
Authorization: Bearer <token>

{
  "id": "store-uuid",
  "type": "identity.user",
  "entity": [
    { "id": "entity-uuid-1" }
  ]
}

Response (200): Returns the EntityRequest confirming the deleted entities.

---

Error Responses

Status	Description
400	Invalid request body, missing required fields, or unknown entity type
403	Authentication failed or insufficient permissions
404	Store or entity not found
500	Internal server error

Related Topics

• Identity Mapper API — High-level identity mapping operations
• Entity Query API — Query entity data store with SSRM filtering
• Datastore API — Low-level entity and edge storage