get_identities

Instructions

Implementation Reference

• src/tools/getIdentities.ts:108-112 (handler)

  The main handler function for get_identities. It gets an API client, converts filters to URL query params, and makes a GET API call to the /identity endpoint.

  export async function getIdentities(filters: IdentityFilters) {
    const client = getClient();
    const queryParams = filtersToParams(filters);
    return client.makeApiCall("/identity", queryParams);
  }

• src/tools/getIdentities.ts:28-104 (schema)

  IdentityFiltersSchema defines the input schema for get_identities: supports filtering by keyword, statuses, types, managementTypes, departments, companies, locations, identityIds, peopleIds, alertTypes, expands, sorting, date ranges, service counts, customFields, booleans, etc.

  export const IdentityFiltersSchema = z.object({
    limit: z.number().optional().describe("Maximum number of items to return per page"),
    cursor: z.string().optional().describe("Cursor for pagination"),
    keyword: z
      .string()
      .optional()
      .describe("Filter results by username, identityId, department name, email or displayName (prefix search)"),
    statuses: z
      .array(z.enum(["active", "on_leave", "draft", "preactive", "retired", "untracked", "archived"]))
      .optional()
      .describe("Filter results by status. Accepts multiple options."),
    types: z.array(z.string()).optional().describe("Filter results by employee type. Accepts multiple options."),
    managementTypes: z
      .array(z.enum(["managed", "external", "system", "unknown", "unregistered"]))
      .optional()
      .describe("Filter results by management type. Accepts multiple options."),
    departments: z.array(z.string()).optional().describe("Filter results by departments. Accepts multiple options."),
    companies: z.array(z.string()).optional().describe("Filter results by companies. Accepts multiple options."),
    locations: z.array(z.string()).optional().describe("Filter results by locations. Accepts multiple options."),
    identityIds: z.array(z.string()).optional().describe("Filter results by identityIds. Accepts multiple options."),
    peopleIds: z.array(z.number()).optional().describe("Filter results by peopleIds. Accepts multiple options."),
    excludeIds: z.array(z.string()).optional().describe("Exclude identities by id. Accepts multiple options."),
    alertTypes: z.array(AlertTypeEnum).optional().describe("Filter results by alert type. Accepts multiple options."),
    expands: z
      .array(IdentityExpandEnum)
      .optional()
      .describe("Expand other datasets when fetching identities. Accepts multiple options."),
    sortBy: IdentitySortByEnum.optional().describe("Sort results by a specific field."),
    sortOrder: z.enum(["ASC", "DESC"]).optional().describe("Sort results in ascending or descending order."),
    contractStartRange: z
      .string()
      .optional()
      .describe("Filter results by contract start date range. Format: YYYY-MM-DD:YYYY-MM-DD, separated by a colon."),
    contractEndRange: z
      .string()
      .optional()
      .describe("Filter results by contract end date range. Format: YYYY-MM-DD:YYYY-MM-DD, separated by a colon."),
    suspensionStartRange: z
      .string()
      .optional()
      .describe("Filter results by suspension start date range. Format: YYYY-MM-DD:YYYY-MM-DD, separated by a colon."),
    suspensionEndRange: z
      .string()
      .optional()
      .describe("Filter results by suspension end date range. Format: YYYY-MM-DD:YYYY-MM-DD, separated by a colon."),
    createdAtRange: z
      .string()
      .optional()
      .describe("Filter results by created date range. Format: YYYY-MM-DD:YYYY-MM-DD, separated by a colon."),
    updatedAtRange: z
      .string()
      .optional()
      .describe("Filter results by updated date range. Format: YYYY-MM-DD:YYYY-MM-DD, separated by a colon."),
    serviceCountFrom: z.number().int().optional().describe("Filter results by minimum service count."),
    serviceCountTo: z.number().int().optional().describe("Filter results by maximum service count."),
    managerId: z.string().optional().describe("Filter results by managerId."),
    serviceId: z.string().optional().describe("Filter results by serviceId."),
    customFields: z
      .record(z.string(), z.string())
      .optional()
      .describe("Filter results by custom fields. For date fields, use date range format: YYYY-MM-DD:YYYY-MM-DD"),
    hasHRM: z
      .boolean()
      .optional()
      .describe("Filter results by HRM (employee master) linkage. When true, returns only UIDs with HRM linkage."),
    haveAssignedDevice: z
      .boolean()
      .optional()
      .describe("Filter results by identities that have at least one assigned device."),
    haveSaasAccount: z.boolean().optional().describe("Filter results by identities that have at least one SaaS account."),
    includeActiveInternalOnly: z
      .boolean()
      .optional()
      .describe(
        "When true, limits results to active employees with internal management (ACTIVE status, MANAGED/SYSTEM types only).",
      ),
  });

• src/index.ts:160-165 (registration)

  Tool registration in the ListToolsRequestSchema handler: defines the tool name 'get_identities', description, and inputSchema referencing IdentityFiltersSchema.

  {
    name: "get_identities",
    description:
      "Return a list of identities. Can be filtered by the status, department and type. Can also search by the email or name by keyword",
    inputSchema: zodToJsonSchema(IdentityFiltersSchema),
  },

• src/index.ts:307-307 (registration)

  Tool handler mapping in toolHandlers: maps 'get_identities' string to a function that parses input with IdentityFiltersSchema and calls getIdentities().

  get_identities: async (input) => getIdentities(IdentityFiltersSchema.parse(input)),

• src/common/helper.ts:1-19 (helper)

  The filtersToParams helper function converts a filters object into URLSearchParams, used by getIdentities to build query parameters for the API call.

  export function filtersToParams(filters: Record<string, any>): URLSearchParams {
    const queryParams = new URLSearchParams();
  
    Object.entries(filters).forEach(([key, value]) => {
      if (value !== undefined && value !== null && !(Array.isArray(value) && value.length === 0)) {
        if (Array.isArray(value) && value.length > 0) {
          // Append each array value separately to generate format: key=value1&key=value2
          value.forEach((item) => {
            queryParams.append(key, String(item));
          });
        } else if (typeof value === "boolean") {
          queryParams.append(key, value.toString());
        } else {
          queryParams.append(key, String(value));
        }
      }
    });
    return queryParams;
  }