REST API

API Reference

Complete REST API documentation for Identity Mesh. Programmatically manage connectors, sync policies, and monitor identity synchronization operations.

GET /connectors

POST /connectors

GET /mesh/objects

POST /mesh/objects/search

GET /instances

POST /connectors/:id/import

GET /rules

POST /rules

Authentication

The Admin API uses Windows Negotiate (Kerberos/NTLM) by default, and also accepts JWT / Entra ID bearer tokens via the SmartAuth policy scheme. Requests must come from an authenticated principal with appropriate permissions. See theAuthentication runbook.

Negotiate + Bearer (SmartAuth)

The API authenticates via Windows Negotiate (Kerberos/NTLM) by default — domain-joined clients authenticate automatically with no keys to manage. The SmartAuth policy scheme also accepts JWT / Entra ID bearer tokens, so cloud-native clients can present an OAuth token instead.

Negotiate by default (Kerberos preferred, NTLM fallback)
JWT / Entra ID bearer via SmartAuth
Role-based access control (RBAC)
Authentication runbook for setup

Example Request

curl --negotiate -u : \
  https://your-server:5001/api/connectors

Base URL

https://your-server:5001/api

The API runs on your on-premises server alongside the sync engine.

Connectors

Manage identity source and target connectors.

GET/connectors

List all configured connectors

Response

{
  "connectors": [
    {
      "id": "conn_abc123",
      "name": "Active Directory",
      "type": "active_directory",
      "status": "active",
      "lastSync": "2026-01-01T18:30:00Z"
    }
  ],
  "total": 1
}

GET/connectors/:id

Get details for a specific connector

Parameters

idConnector ID

POST/connectors

Create a new connector

Request Body

{
  "name": "Active Directory",
  "type": "active_directory",
  "config": {
    "host": "ldap.company.com",
    "port": 636,
    "baseDN": "dc=company,dc=com",
    "bindDN": "cn=admin,dc=company,dc=com",
    "bindPassword": "********"
  }
}

PUT/connectors/:id

Update connector configuration

DELETE/connectors/:id

Delete a connector

Rules

Create and manage sync rules — join rules, flow rules, projection rules, and MeshComposer rules.

GET/rules

List all rules, optionally filtered by connector or rule type

Response

{
  "items": [
    {
      "ruleId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ruleName": "Join on employeeId",
      "ruleType": "JoinRule",
      "connectorId": "conn_abc123",
      "priority": 1,
      "isEnabled": true
    }
  ],
  "totalCount": 1
}

POST/rules

Create a new rule (JoinRule, FlowRule, ProjectionRule, or MeshComposerRule)

Request Body

{
  "ruleName": "Flow displayName from AD",
  "ruleType": "FlowRule",
  "connectorId": "conn_abc123",
  "sourceAttribute": "displayName",
  "targetAttribute": "displayName",
  "confidence": 90,
  "transformScript": "Trim(source)"
}

Import & Export Operations

Trigger and monitor import and export operations on connectors.

POST/connectors/:id/import

Trigger a full or delta import on a connector

Response

{
  "runId": "run_123abc",
  "connectorId": "conn_abc123",
  "runType": "DeltaImport",
  "status": "Running",
  "startedAt": "2026-01-01T19:00:00Z"
}

POST/connectors/:id/export

Trigger an export to write pending changes to a target connector

GET/runs/:id

Get status of an import or export run

Response

{
  "runId": "run_123abc",
  "connectorId": "conn_abc123",
  "runType": "DeltaImport",
  "status": "Completed",
  "startedAt": "2026-01-01T19:00:00Z",
  "completedAt": "2026-01-01T19:02:15Z",
  "stats": {
    "objectsProcessed": 1250,
    "objectsCreated": 45,
    "objectsUpdated": 203,
    "objectsDeleted": 12,
    "errors": 0
  }
}

Engine Instances

Manage sync engine instances — list, pause, resume, rename, and remove.

GET/instances

List all registered engine instances with effective status

POST/instances/:id/pause

Pause a specific engine instance

POST/instances/:id/resume

Resume a paused engine instance

PUT/instances/:id/rename

Rename an instance. Cascades across connector assignments, run history, and pause settings. Returns 409 if the new name is already taken.

DELETE/instances/:id

Remove an offline instance and unassign its connectors

PUT/connectors/:id/instance

Assign or unassign a connector to an instance. A connector already assigned to another instance must be unassigned first (409 Conflict).

Mesh Objects

Query the unified identity mesh. List, search, and inspect mesh objects with their consolidated attributes from all connected sources.

GET/mesh/objects

List mesh objects with pagination, type filtering, and anchor search

Parameters

skipNumber of records to skip (pagination offset)

takeNumber of records to return (max 200)

objectTypeFilter by object type (optional)

searchFilter by anchor value substring (optional)

Response

{
  "items": [
    {
      "meshObjectId": "c51d176b-0c9e-4b59-80bd-cb49078d9044",
      "objectType": "User",
      "anchorValue": "jsmith@company.com",
      "createdOn": "2026-01-15T10:30:00Z",
      "updatedOn": "2026-02-01T14:22:00Z",
      "attributeValues": {
        "displayName": "John Smith",
        "department": "Engineering",
        "title": "Senior Developer",
        "mail": "jsmith@company.com"
      }
    }
  ],
  "totalCount": 1,
  "skip": 0,
  "take": 25
}

Each object includes an attributeValues dictionary containing all consolidated attribute name/value pairs, enabling dynamic column display without additional API calls.

POST/mesh/objects/search

Advanced search with attribute-based criteria

Request Body

{
  "objectType": "User",
  "anchorSearch": "smith",
  "criteria": [
    {
      "attributeName": "department",
      "operator": "equals",
      "value": "Engineering"
    }
  ],
  "skip": 0,
  "take": 25
}

Supported operators: equals,contains,startswith,endswith,ispresent,isnotpresent,istrue,isfalse. Multiple criteria are combined with AND logic.

GET/mesh/objects/:id

Get full mesh object detail with attributes and relationships

Response

{
  "meshObjectId": "c51d176b-0c9e-4b59-80bd-cb49078d9044",
  "objectType": "User",
  "anchorValue": "jsmith@company.com",
  "createdOn": "2026-01-15T10:30:00Z",
  "updatedOn": "2026-02-01T14:22:00Z",
  "attributes": [
    {
      "attributeName": "displayName",
      "attributeValue": "John Smith",
      "source": "14d98031-df8d-45cd-8476-1d6dcc02407e",
      "confidence": 100,
      "updatedOn": "2026-02-01T14:22:00Z"
    }
  ],
  "relationships": [
    {
      "relationshipType": "manager",
      "targetMeshObjectId": "a23b456c-...",
      "targetAnchorValue": "mjones@company.com",
      "targetObjectType": "User"
    }
  ]
}

The detail view returns the full attribute array (with source connector, confidence score, and timestamp per attribute) and all relationships to other mesh objects.

API Notes

The Admin API runs on-premises alongside your sync engine. There are no external rate limits.

All responses return standard JSON with consistent pagination

HTTPS required — the API binds to port 5001 by default

CORS is enabled for the Admin UI origin

Error Codes

Standard HTTP status codes with detailed error messages.

400Bad Request

Invalid request parameters

401Unauthorized

Authentication failed (Negotiate or bearer)

404Not Found

Resource does not exist

429Too Many Requests

Rate limit exceeded

500Internal Server Error

Server-side error occurred

Connector SDK

Build custom connectors using the IIdentityConnector SDK to integrate any identity source.

IIdentityConnector

.NET interface

Implement FullImport(), DeltaImport(), and Export() to connect any identity source.

Active Directory

Built-in connector

LDAP-based connector with uSNChanged delta detection, group membership sync, and OU-aware operations.

SQL Database

Built-in connector

Configurable SQL queries for import, configurable delta columns, and parameterized export statements.

Ready to Get Started?

Request API access and start building with Identity Mesh today.

Request API Access View Getting Started Guide