Credential Lookup: Setup and User Guide

This guide explains the IDMS Credential Lookup feature: what it does, how to switch it on, who can use it, how to call it from another application, and how to check that it is running well. It is written for administrators who are new to the feature. You do not need to edit any configuration files.

1. Overview

Credential Lookup lets another application, such as a badge reader station or an access control system, find a person in IDMS from a single value it has scanned or typed, such as a badge barcode. It sends the value to IDMS and gets back, in one quick answer:

2. What it does and how it works

2.1 Searchable fields

The values you look up come from the questions on a credential type's intake form, for example a "Badge barcode" question. An administrator chooses which intake questions can be searched by ticking Searchable next to them. Each credential type has its own choices, so different credential types can be searched by different fields.

2.2 How a lookup finds the person

1. When a person's answer to a searchable question is saved, IDMS creates a fingerprint of the value and stores it in a search index. The fingerprint is a one-way code made with a secret key, so the index never contains the readable value.

2. When an application looks up a value, IDMS makes the fingerprint of that value and finds the matching entry in the index. This takes a few milliseconds, even with very large numbers of people.

3. IDMS then reads the person's name, network user ID, latest request status and badge type, and returns them.

2.3 Things worth knowing

• Exact match only. The value must match the stored answer exactly, except that spaces before and after the value are ignored and, for numbers, leading zeros are ignored (000123 matches 123). Partial or "starts with" searches are not supported.

• Freshness. Answers are remembered for up to 60 seconds to keep lookups fast. A change in IDMS (for example a request moving to ISSUED) appears in lookups within 60 seconds.

• Index upkeep is automatic. The index is updated whenever a person is enrolled, edited, moved to another credential type or expunged. When you tick Searchable on a credential type that already has people, IDMS indexes them in the background. A nightly job checks the whole index and repairs anything that is out of step (see section 7).

• Privacy. Readable values are never stored in the index and never written to the log. Expunged people are removed from the index, so they cannot be found.

• Duplicates. If two people have the same value in a searchable field, a lookup returns "ambiguous" (409) rather than guessing. The IDMS log names both people so you can correct the data.

• Auditing. Every time someone ticks or unticks Searchable, IDMS writes an audit entry with the operator, credential type, field and change (audit transaction type SrchIdxCfg).

3. Configuration requirements

There is nothing to install and no configuration file to edit.

3.1 Setup steps

Step 1: Choose the searchable field (needs the SystemManager role)

1. Go to Administration > Credential Types.

2. Open the credential type (policy) whose people you want to find.

3. In the Intake Form grid, find the question that holds the value, for example barCode.

4. Tick Searchable for that question. Hover over the column heading for guidance.

5. Save the credential type.

6. Repeat for every credential type whose people should be found.

Notes:

• Searchable can only be ticked for text fields (text box, text area, IDMS user ID). Files, PDFs, photos and signatures cannot be searched.

• Choose fields whose values are unique to one person, such as a badge number. Do not make fields with only a few possible answers searchable (yes/no, department, and so on).

• Existing people on that credential type are indexed in the background straight after you save. Large credential types can take a few minutes. The IDMS log shows when the background indexing starts and finishes.

Step 2: Create the account the calling application will use (needs the SystemManager role)

1. Go to Administration > Operators and add an operator for the application, for example "Badge Station Service".

2. Enter the Certificate Thumbprint of the client certificate the application will present.

3. Assign the role BadgeLookup.

Give this account only the roles it needs. Use a separate account for each application so their traffic can be told apart in the logs.

Step 3: Give monitoring access (optional, needs the SystemManager role)

1. Go to Administration > Operators and open each person who should see the Performance tab.

2. Assign the role SystemMonitor. These people also need SystemManager, because the tab is on the Administration > System Connections page.

3. If a monitoring dashboard will call the detailed status API, create a separate account for it with SystemMonitor, so it does not share the status call limit with people using the screen.

Step 4: Test it

Use the PowerShell sample in section 6.3 with a value you know exists. You should get 200 and the person's details.

4. Roles required

Both new roles (BadgeLookup and SystemMonitor) are added to IDMS automatically when it starts. You only need to assign them.

5. Calling the lookup API

5.1 The basics

Every call needs a token. The application gets a token once, keeps it, and sends it with each lookup.

• <value> is the scanned value. URL-encode it if it can contain anything other than letters and numbers.

• attribute is the intake field name (its dataName), for example barCode. It is optional but recommended: it makes the lookup faster and avoids ambiguous results. Without it, every searchable field is searched.

• Tokens last 1 day. Request one token, reuse it for all lookups, and renew it every hour. Do not request a new token for every scan.

5.2 Answers you can get

A successful lookup (200 OK):

{
  "userId": 1000015058,
  "firstName": "Jane",
  "middleName": "A",
  "lastName": "Doe",
  "networkUserId": "jdoe01",
  "requestStatus": "APPROVED",
  "badgeType": "DCMLL",
  "matchedAttribute": "barCode",
  "asOf": "2026-10-12T14:03:22Z"
}

asOf is when the details were read from the database (up to 60 seconds earlier).

Error bodies look like { "error": "NotFound" }. 429 and 503 bodies also include retryAfterSeconds.

Every answer includes a Server-Timing header showing how long IDMS took, for example db;dur=3.2, total;dur=5.1 (milliseconds).

5.3 Good practice for the calling application

• Always wait for Retry-After on 429 and 503. Retrying immediately makes the overload worse.

• Never retry 400, 403, 404 or 409. The answer will not change.

• If many stations share one application, the application should call IDMS on their behalf and share the results, rather than each station calling separately. This also applies to the status API.

• Optionally send an X-Station-Id header naming the station. IDMS can log it to help trace problems.

6. Sample API calls

Replace <https://idms.example.com/WebApi,> the certificate thumbprint and the values with your own.

6.1 PowerShell: get a token and look up a value

Works in Windows PowerShell 5.1 and PowerShell 7. The client certificate must be in the current user's certificate store.

$baseUrl    = "https://idms.example.com/WebApi"
$thumbprint = "<client certificate thumbprint>"
$cert       = Get-Item -Path (Join-Path "Cert:\CurrentUser\My" $thumbprint)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# 1. Get a token (once; reuse it and renew it hourly)
$token = Invoke-RestMethod -Method Post -Uri "$baseUrl/Token" -Certificate $cert `
    -ContentType "application/x-www-form-urlencoded" `
    -Body "grant_type=password&username=apiuser&password=unused"
$headers = @{ Authorization = "Bearer $($token.access_token)" }

# 2. Look up a badge barcode
$value = [uri]::EscapeDataString("1234567890")
try {
    $person = Invoke-RestMethod -Method Get -Uri "$baseUrl/api/v2/lookup/$($value)?attribute=barCode" `
        -Headers $headers -Certificate $cert
    "$($person.firstName) $($person.lastName): $($person.requestStatus), $($person.badgeType)"
}
catch {
    $code = [int]$_.Exception.Response.StatusCode
    "Lookup failed with HTTP $code"
}

6.2 PowerShell: check the status

# Basic status (role BadgeLookup): ok, degraded or unavailable
Invoke-RestMethod -Uri "$baseUrl/api/v2/status" -Headers $headers -Certificate $cert

# Detailed status (role SystemMonitor)
Invoke-RestMethod -Uri "$baseUrl/api/v2/status/detail" -Headers $headers -Certificate $cert |
    ConvertTo-Json -Depth 6

6.3 PowerShell: quick test with status code and timing

Use this in Step 4 of the setup to see exactly what IDMS returns, including errors.

$response = Invoke-WebRequest -Uri "$baseUrl/api/v2/lookup/1234567890?attribute=barCode" `
    -Headers $headers -Certificate $cert -UseBasicParsing -SkipHttpErrorCheck
"Status: $($response.StatusCode)"
"Timing: $($response.Headers['Server-Timing'])"
$response.Content

-SkipHttpErrorCheck needs PowerShell 7. In Windows PowerShell 5.1, remove it; error codes then appear as exceptions, as in 6.1.

6.4 curl (Windows)

The curl that comes with Windows can use a certificate from the Windows certificate store:

curl -s -X POST "https://idms.example.com/WebApi/Token" \
  --cert "CurrentUser\My\<thumbprint>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=apiuser&password=unused"

curl -s -i "https://idms.example.com/WebApi/api/v2/lookup/1234567890?attribute=barCode" \
  --cert "CurrentUser\My\<thumbprint>" \
  -H "Authorization: Bearer <access_token>"

On Linux or macOS, use the certificate file instead, for example --cert-type P12 --cert client.pfx:<pfx password>.

6.5 C# (.NET): reuse one client and one token

using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;

public sealed class CredentialLookupClient
{
    private readonly HttpClient _http;
    private string _token;
    private DateTime _tokenExpires = DateTime.MinValue;

    public CredentialLookupClient(string baseUrl, X509Certificate2 clientCertificate)
    {
        var handler = new HttpClientHandler();
        handler.ClientCertificates.Add(clientCertificate);
        _http = new HttpClient(handler) { BaseAddress = new Uri(baseUrl.TrimEnd('/') + "/") };
    }

    public async Task<string> LookupAsync(string value, string attribute = "barCode")
    {
        await EnsureTokenAsync();
        var request = new HttpRequestMessage(HttpMethod.Get,
            "api/v2/lookup/" + Uri.EscapeDataString(value) + "?attribute=" + Uri.EscapeDataString(attribute));
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _token);

        HttpResponseMessage response = await _http.SendAsync(request);
        if (response.StatusCode == (HttpStatusCode)429 || response.StatusCode == HttpStatusCode.ServiceUnavailable)
        {
            TimeSpan wait = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(5);
            await Task.Delay(wait);   // wait as told, then let the caller try again
            return null;
        }
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return null;              // not found: do not retry
        }
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();   // JSON with the person's details
    }

    private async Task EnsureTokenAsync()
    {
        if (_token != null && DateTime.UtcNow < _tokenExpires)
        {
            return;
        }
        var body = new FormUrlEncodedContent(new[]
        {
            new System.Collections.Generic.KeyValuePair<string, string>("grant_type", "password"),
            new System.Collections.Generic.KeyValuePair<string, string>("username", "apiuser"),
            new System.Collections.Generic.KeyValuePair<string, string>("password", "unused")
        });
        HttpResponseMessage response = await _http.PostAsync("Token", body);
        response.EnsureSuccessStatusCode();
        dynamic json = Newtonsoft.Json.JsonConvert.DeserializeObject(await response.Content.ReadAsStringAsync());
        _token = (string)json.access_token;
        _tokenExpires = DateTime.UtcNow.AddHours(1);   // renew hourly
    }
}

Create one CredentialLookupClient when the application starts and use it for every scan.

7. Background jobs (Job Scheduler)

Credential Lookup uses two background tasks. Neither needs setting up.

7.1 Background indexing (runs on its own)

When someone ticks Searchable on a credential type and saves, IDMS indexes that credential type's existing people in the background. It works in small batches with short pauses so it does not slow IDMS down. When someone unticks Searchable, IDMS removes that field's index entries for the credential type. Both are recorded in the IDMS log.

7.2 Nightly check and repair: SearchableIndexReconciliationJobManager

Pause or resume it: on the Job Scheduling tab, use the pause or play button on the job's row.

Change when it runs: click the cog button on the job's row and change the schedule. The schedule uses Quartz cron format (seconds, minutes, hours, day of month, month, day of week):

Choose a quiet time. The job reads every person on credential types with a searchable field, so on large systems it can take a while.

Run it now: a SystemManager account can start it straight away with POST <https://<server>>/WebApi/api/SearchableIndex/StartReconciliation. To index a single credential type again, use POST <https://<server>>/WebApi/api/SearchableIndex/StartBackfill?policyKey=<credential type key>. Both return straight away; the work continues in the background and is logged.

7.3 External systems health check: HealthCheckerJobManager

The External systems card on the Performance tab shows the latest result of the existing IDMS health check job. That job is installed paused. If the card says the check hasn't run, resume HealthCheckerJobManager on the Job Scheduling tab. It does not affect lookups.

8. Monitoring performance

8.1 The Performance tab

Go to Administration > System Connections and open the Performance tab. You need the SystemManager and SystemMonitor roles.

• The figures refresh every 20 seconds while the tab is open. Use Refresh for an immediate update, or Pause to stop.

• Each card has an (i) button at its top right. Click it for a plain explanation of the card.

When to act:

If you run several IDMS servers behind a load balancer, each server has its own figures. The banner shows which server answered.

8.2 Status APIs for dashboards

• The figures are measured every 10 seconds, so calling more often gives the same answer.

• Each account may call each status API 6 times a minute. More calls get 429. Poll every 20 to 30 seconds.

8.3 The IDMS log

By default the IDMS WebApi log is c:\\temp\\idexchangeWebApi.txt on the IDMS server. Useful lines:

Readable lookup values are never written to the log.

8.4 Built-in limits

These protect IDMS from overload. They suit most sites and do not need changing.

If your traffic needs different limits, they can be overridden in Web.config. See the separate note "Badge Lookup: Optional Rate-Limit Settings" before changing them.

9. Troubleshooting