Identity Mapper API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The Identity Mapper API provides programmatic access to Hydden's identity mapping engine. Use these endpoints to check mapping status, test regex rules before deploying them, preview how a rule would affect accounts, trigger a full mapping run, and prune orphaned owners.

Source: src/iam/mapper/rest/rest.go

Base Path

/internal/v1/idmapper

Authentication

All endpoints require JWT cookie or API token authentication.

Endpoints

Method	Path	Description	Auth required
GET	/internal/v1/idmapper/status	Get mapper status and last run statistics	JWT + API token
POST	/internal/v1/idmapper/rule/test	Test a regex pattern against a string	JWT + API token
POST	/internal/v1/idmapper/rule/preview	Preview a mapping rule's impact on accounts	JWT + API token
POST	/internal/v1/idmapper/run	Trigger an identity mapping run	JWT + API token
POST	/internal/v1/idmapper/prune	Delete all unmapped (orphaned) owners	JWT + API token

---

GET /internal/v1/idmapper/status

Get the current status of the identity mapper, including statistics from the last mapping run.

Request:

GET /internal/v1/idmapper/status
Authorization: Bearer <token>

Response (200):

{
  "lastMapStart": 1707700800000,
  "lastMapFinish": 1707701100000,
  "orphanCount": 23,
  "mappedAccounts": 4521,
  "newIdentities": 12,
  "deletedIdentities": 3
}

Response fields:

Field	Type	Description
lastMapStart	int64	Timestamp (ms) when the last mapping run started
lastMapFinish	int64	Timestamp (ms) when the last mapping run completed
orphanCount	int64	Number of owners with no mapped accounts
mappedAccounts	int64	Total number of accounts currently mapped to owners
newIdentities	int64	Identities created during the last run
deletedIdentities	int64	Identities removed during the last run

---

POST /internal/v1/idmapper/rule/test

Test a regex pattern and optional replacement against a test string. Use this to validate mapping rule patterns before saving them.

Request:

POST /internal/v1/idmapper/rule/test
Content-Type: application/json
Authorization: Bearer <token>

{
  "pattern": "^(.+)@company\\.com$",
  "replace": "$1",
  "testString": "john.doe@company.com"
}

Request fields:

Field	Type	Required	Description
pattern	string	Yes	Regex pattern to test
replace	string	No	Replacement string (supports $1, $2 capture groups)
testString	string	Yes	String to test the pattern against

Response (200):

{
  "match": true,
  "result": "john.doe",
  "error": false
}

Response fields:

Field	Type	Description
match	bool	Whether the pattern matched the test string
result	string	Result after applying pattern and replacement
error	bool	Whether the regex compilation failed

---

POST /internal/v1/idmapper/rule/preview

Preview the effect of a mapping rule on actual account data. Returns a list of accounts that would match, along with the identity they would map to.

Request:

POST /internal/v1/idmapper/rule/preview
Content-Type: application/json
Authorization: Bearer <token>

{
  "rule": {
    "ruleCategory": "email",
    "matchTemplate": "email",
    "matchProperty": "email",
    "pattern": "^(.+)@company\\.com$",
    "replace": "$1",
    "accountType": ["User"],
    "classifications": [],
    "accountTemplate": "upn",
    "createOption": 1,
    "max": 100,
    "dataSourceId": "",
    "accountFilter": "",
    "showAll": false,
    "providerFilter": "",
    "showMapped": true
  }
}

Key request fields:

Field	Type	Description
ruleCategory	string	Rule category (e.g., email, upn, custom)
matchTemplate	string	Template for matching (e.g., email, upn, samaccountname)
matchProperty	string	Account property to match against
pattern	string	Regex pattern for matching
replace	string	Replacement string with capture groups
accountType	string[]	Filter by account types (User, Service, etc.)
classifications	string[]	Filter by account classifications
createOption	int32	Owner creation behavior (0=none, 1=create if needed)
max	int32	Maximum accounts to return in preview
dataSourceId	string	Filter to a specific data source (empty = all)
showAll	bool	Show all accounts, not just matches
showMapped	bool	Include already-mapped accounts

Response (200):

{
  "uniqueId": "rule-preview-uuid",
  "error": false,
  "reason": "",
  "accounts": [
    {
      "id": "acct-uuid-1",
      "name": "jdoe",
      "displayName": "John Doe",
      "email": "john.doe@company.com",
      "matchedOnValue": ["john.doe@company.com"],
      "platform": "Azure AD",
      "dataSourceId": "ds-uuid",
      "dataSource": "Corporate Azure",
      "accountType": "User",
      "mappedIdentity": "owner-uuid",
      "mappedName": "John Doe",
      "upn": "john.doe@company.com",
      "match": true,
      "reason": "",
      "provider": "AzureAD"
    }
  ],
  "numAccounts": 1,
  "numOrphans": 0
}

---

POST /internal/v1/idmapper/run

Trigger the identity mapper to execute a full mapping run. The mapper processes all accounts against configured mapping rules and creates or updates owner-to-account relationships.

Request:

POST /internal/v1/idmapper/run
Authorization: Bearer <token>

No request body required.

Response (200):

Returns the same IdmapperStatus structure as the status endpoint, reflecting the newly initiated run.

{
  "lastMapStart": 1707701200000,
  "lastMapFinish": 0,
  "orphanCount": 23,
  "mappedAccounts": 4521,
  "newIdentities": 0,
  "deletedIdentities": 0
}

Note: The lastMapFinish will be 0 while the run is in progress. Poll the status endpoint to check completion.

---

POST /internal/v1/idmapper/prune

Delete all owner identities that are not currently mapped to any account. This permanently removes orphaned owners from the system.

Request:

POST /internal/v1/idmapper/prune
Authorization: Bearer <token>

No request body required.

Response (200):

Returns the same IdmapperStatus structure with updated orphanCount (expected to be 0 after successful prune) and updated deletedIdentities count.

{
  "lastMapStart": 1707701200000,
  "lastMapFinish": 1707701500000,
  "orphanCount": 0,
  "mappedAccounts": 4521,
  "newIdentities": 0,
  "deletedIdentities": 23
}

Caution: This operation is destructive. Pruned owners cannot be recovered. Verify the orphan count via the status endpoint before pruning.

---

Error Responses

Status	Description
400	Invalid request body or malformed regex pattern
403	Authentication failed or insufficient permissions
500	Internal server error during mapping or prune operation

Related Topics

• Entity Query API — Query identity data store
• Entity Management API — Low-level entity index operations
• Identity Mapping — User-facing mapping rule configuration
• Owner Creation — Automatic owner creation rules