platform sdk mobile credentials

About mobile credentials

A mobile credential is a credential that is stored on a phone or watch instead of a physical card. In Security Center, the credential is still a Credential entity assigned to a Cardholder, but the card number is reserved with HID Origo and delivered to the cardholder's device through an invitation.

The Platform SDK provides an HID Origo client that authenticates against your HID Origo configuration, manages mobile users and their devices, issues and revokes mobile IDs, and returns the card number you bind to the Security Center Credential entity. All client operations are asynchronous and accept a CancellationToken.

Mobile credential lifecycle

A mobile credential progresses through stages spanning the HID Origo service, the cardholder's device, and the Security Center entity model. Each transition is driven either by an SDK call or by the cardholder.

flowchart LR
    Created[Mobile user created] -- "CreateInvitation<br/>SendInvitation" --> Invited[Invitation sent]
    Invited -- "Cardholder registers<br/>HID Origo app" --> Registered[Device registered]
    Registered -- "IssueMobileId" --> Issued[Mobile ID issued]
    Issued -- "CredentialBuilder.Build" --> Active[Credential active in Security Center]
    Active -- "RevokeId" --> Revoked[Mobile ID revoked]
    Revoked -- "engine.DeleteEntity<br/>DeleteUser" --> Removed[Cleanup complete]

Loading

Stage	What exists	Driven by
Mobile user created	MobileCredentialUser with ExternalId set to the cardholder GUID	CreateUser
Invitation sent	MobileInvitation linked to the user; the cardholder receives an email	CreateInvitation then SendInvitation, or the auto-assignment overload of CreateUser
Device registered	A MobileCredentialDevice appears in MobileCredentialUser.Devices	The cardholder installing the HID Origo app and entering the invitation code
Mobile ID issued	A MobileCredential with a populated CardNumber	IssueMobileId, or as a side effect of CreateUser with assignCredential: true
Credential active in Security Center	A Credential entity assigned to the cardholder, using the matching CredentialFormat	EntityManager.GetCredentialBuilder and Build
Mobile ID revoked	The mobile ID is invalidated at HID Origo but the Security Center entity still exists	RevokeId
Cleanup complete	The Security Center Credential entity is deleted; optionally the mobile user is removed at HID Origo	engine.DeleteEntity and DeleteUser

Prerequisites

Before you can issue a mobile credential through the SDK:

• Security Center license includes at least one Mobile Credential Manager (License.NumberOfMobileCredentialManagers greater than zero).
• A Mobile Credential Manager role is created and online, with at least one server assigned. Only one Mobile Credential Manager role exists per Security Center system.
• A mobile credential profile is configured on the Mobile Credential Manager role's Configuration tab, with a valid part number, card format, and (depending on the format) facility code or company id.
• The user account running the SDK application holds the CreateMobileCredential privilege.
• HID Origo configuration values are available. baseUrl, idpUrl, contentType, applicationVersion, and resourceType ship in the MobileAccessProviders.gconfig file installed with Security Center (see Locating HID Origo configuration values). applicationId comes from your HID Origo integration configuration. customerId, clientId, and the client secret come from your HID Origo tenant.

Locating HID Origo configuration values

Five of the values you pass to HidOrigoMobileCredentialConfiguration are stored in MobileAccessProviders.gconfig, an XML file installed by Security Center. The default location is C:\Program Files (x86)\Genetec Security Center <version> on both the server and any client running Config Tool or Security Desk.

Each provider is a <Provider> element. Read the element whose Type attribute is HIDV2Origo. Its attributes map to the constructor parameters as follows:

<Provider> attribute	HidOrigoMobileCredentialConfiguration parameter
APIUri	baseUrl
TokenUri	idpUrl
LegacyTokenUri	idpUrl (when calling the isLegacyIdp: true overload)
ContentType	contentType
ApplicationVersion	applicationVersion
ResourceType	resourceType

LegacyTokenUri is optional and only present when the deployment still needs the legacy HID identity provider.

applicationId is not stored in this file. Obtain it from your HID Origo integration configuration.

Note

The URL values in this file changed in Security Center 5.13.3.0. When integrating against that release, apply the updated values from KBA-79270 in the Genetec Tech Doc Hub. The issue is fixed in 5.13.3.1.

Mobile credential providers

A MobileCredentialProvider represents a mobile credential profile configured on the Mobile Credential Manager role. Config Tool calls these "mobile credential profiles"; the SDK exposes them as MobileCredentialProvider instances. Retrieve providers from SystemConfiguration:

var systemConfig = engine.GetEntity<SystemConfiguration>(
    SystemConfiguration.SystemConfigurationGuid);

var allProviders = systemConfig.GetMobileCredentialProviders();

var origoProviders = systemConfig.GetMobileCredentialProviderByType(
    MobileCredentialProviderType.HIDV2Origo);

var provider = systemConfig.GetMobileCredentialProviderByProviderId(providerGuid);

The provider exposes these properties:

Property	Type	Purpose
ProviderId	Guid	The provider's unique id, used with GetMobileCredentialProviderByProviderId
Name	string	The profile's display name as shown in Config Tool
Description	string	The profile's description as shown in Config Tool
Type	MobileCredentialProviderType	The provider technology. HIDV2Origo corresponds to the HID Mobile - Origo profile type in Config Tool
PartNumber	string	The part number name passed to CreateUser, CreateInvitation, and IssueMobileId
PartNumberId	string	The id passed to GetMobileIdsByPartNumber, GetActiveMobileIds, GetRevokedMobileIds, and GetPartNumberDetails
CardFormat	Guid	The Security Center card format identifier used to build the matching CredentialFormat
FacilityCode	int	The facility code applied to Wiegand 26-bit, H10304, H10306 formats
CompanyId	string	The company id applied to Corporate 1000 (35-bit) and Corporate 1000 (48-bit) formats. Must parse as int for GetCredentialFormat to return a populated format
CustomerId	string	The HID Origo customer id. Config Tool labels this field Organization ID in the mobile credential profile editor
State	ProviderState	The provider's current configuration-transition state. Values are None (no pending operation), Creating, Editing, and Deleting

Card format mapping

MobileCredentialProvider.GetCredentialFormat(long) returns the matching CredentialFormat based on the provider's CardFormat, FacilityCode, and CompanyId. Use this table to confirm that a provider is compatible with the issuance flow before you call IssueMobileId:

Provider card format	Returned CredentialFormat type	Required provider field
Wiegand 26-bit	WiegandStandardCredentialFormat	FacilityCode
H10302	WiegandH10302CredentialFormat	None (card number only)
H10304	WiegandH10304CredentialFormat	FacilityCode
H10306	WiegandH10306CredentialFormat	FacilityCode
Corporate 1000 (35-bit)	WiegandCorporate1000CredentialFormat	CompanyId (must parse as int)
Corporate 1000 (48-bit)	Wiegand48BitCorporate1000CredentialFormat	CompanyId (must parse as int)

GetCredentialFormat returns null for any card format outside this set, and for either Corporate 1000 format when CompanyId cannot be parsed as an integer. Always check the returned value before calling SetFormat on the credential builder.

Creating an HID Origo client

Build a HidOrigoMobileCredentialConfiguration and call CreateOrigoClient on the Engine's MobileCredentialManager. Keep the secret in a SecureString and clear any plaintext source as soon as the configuration is built.

var hidConfig = new HidOrigoMobileCredentialConfiguration(
    baseUrl,
    idpUrl,
    contentType,
    applicationVersion,
    applicationId,
    resourceType);

IMobileCredentialClient client = engine.MobileCredentialManager
    .CreateOrigoClient(hidConfig, customerId, clientId, secret);

Reuse the same IMobileCredentialClient instance for the lifetime of your integration.

A second HidOrigoMobileCredentialConfiguration constructor accepts a pre-built HidOrigoConfiguration instance. Use the string-based constructor shown above for new integrations.

Using the legacy identity provider URL

If your HID Origo configuration still uses the legacy identity provider (IDP) endpoint, set isLegacyIdp to true. The same idpUrl value is then stored as the legacy URL.

var hidConfig = new HidOrigoMobileCredentialConfiguration(
    baseUrl,
    idpUrl,
    contentType,
    applicationVersion,
    applicationId,
    resourceType,
    isLegacyIdp: true);

Authenticating the client

Call AuthenticateClient once after construction. Every other method on IMobileCredentialClient requires an authenticated client.

await client.AuthenticateClient(cancellationToken);

Important

Calls made before AuthenticateClient completes fail. Authenticate the client at startup, or before the first issuance, and reuse the client across operations.

Issuing a mobile credential to a cardholder

Issuance has two halves. On the HID Origo side, you create a mobile user, send the user an invitation, wait for the cardholder to register the app on a device, and then issue a mobile ID against the device and the provider's part number. On the Security Center side, you build a Credential entity using the card format that matches the provider, and assign it to the cardholder.

Create the mobile user

Pass the cardholder GUID as the external id so you can correlate the mobile user back to Security Center later through MobileCredentialUser.ExternalId:

var cardholder = engine.GetEntity<Cardholder>(cardholderGuid);

var mobileUser = await client.CreateUser(
    givenName: cardholder.FirstName,
    familyName: cardholder.LastName,
    userExternalID: cardholderGuid,
    email: cardholder.EmailAddress,
    cancellationToken);

Create and send the invitation

The CreateInvitation overload only creates the invitation record. Call SendInvitation with the invitation id to deliver the email:

var invitation = await client.CreateInvitation(mobileUser.Id, cancellationToken);
await client.SendInvitation(invitation.Id, cancellationToken);

Wait for device registration

Wait for the cardholder to install the HID Origo app and register their device with the invitation code. Once they have, refresh the user record and pick the registered device:

mobileUser = await client.GetUser(mobileUser.Id, cancellationToken);
var deviceId = mobileUser.Devices.First().Id;

Issue the mobile ID

Issue the mobile ID against the device and the provider's part number. The returned MobileCredential.CardNumber is the card number you bind to the Security Center credential:

var mobileCredential = await client.IssueMobileId(
    deviceId,
    assignCredential: true,
    partNumberName: provider.PartNumber,
    cancellationToken);

Build the Security Center credential

Build the matching CredentialFormat and create the Security Center Credential entity. MobileCredentialProvider.GetCredentialFormat(long) returns a populated format for Wiegand 26-bit, H10302, H10304, H10306, Corporate 1000 (35-bit), and Corporate 1000 (48-bit) providers. It returns null for any other card format, and for the Corporate 1000 formats when CompanyId cannot be parsed as an integer:

var format = provider.GetCredentialFormat(mobileCredential.CardNumber);
if (format == null)
{
    throw new InvalidOperationException(
        "Provider card format is not supported by GetCredentialFormat.");
}

var builder = engine.EntityManager.GetCredentialBuilder();
builder.SetName($"Mobile - {cardholder.LastName}")
       .SetFormat(format)
       .SetCardholder(cardholder);

Credential credential = builder.Build();

Issuing with auto-assignment

To create the invitation, send the email, and reserve a card number in a single round trip, use the extended CreateUser overload. The reserved card number is returned in MobileCredentialUser.UnregisteredCredentials:

var mobileUser = await client.CreateUser(
    givenName: cardholder.FirstName,
    familyName: cardholder.LastName,
    userExternalID: cardholderGuid,
    email: cardholder.EmailAddress,
    createInvitationCode: true,
    assignCredential: true,
    sendInvitationEmail: true,
    partNumberName: provider.PartNumber,
    cancellationToken);

var unregistered = mobileUser.UnregisteredCredentials.FirstOrDefault();
if (unregistered == null)
{
    return;
}

var format = provider.GetCredentialFormat(unregistered.CardNumber);
if (format == null)
{
    return;
}

var builder = engine.EntityManager.GetCredentialBuilder();
builder.SetName($"Mobile - {cardholder.LastName}")
       .SetFormat(format)
       .SetCardholder(cardholder);

builder.Build();

The card number is reserved against the part number at this point. The mobile ID becomes active on the cardholder's device once they accept the invitation and register the app.

When the mobile user already exists and you only need to issue a new invitation with a reserved card number, use the extended CreateInvitation overload. It returns both the MobileInvitation and the MobileCredential:

var (invitation, credential) = await client.CreateInvitation(
    mobileUserId,
    partNumberName: provider.PartNumber,
    sendInvitationEmail: true,
    assignCredential: true,
    cancellationToken);

Re-issuing on a replacement device

When a cardholder replaces their phone, their existing mobile ID stays bound to the old device id. The existing Security Center Credential entity stays bound to the old card number. To move the cardholder to a new phone, issue a new mobile ID against the new device, build a new Credential entity with the new card number, and retire the old mobile ID and entity.

Identify the new device

Track the previous device id from your application state, and then pick the device on the user record that does not match it:

var mobileUser = await client.GetUser(mobileUserId, cancellationToken);
var newDevice = mobileUser.Devices
    .First(device => device.Id != oldDeviceId);

Issue the new mobile ID

Issue a new mobile ID against the new device and the same part number:

var newMobileCredential = await client.IssueMobileId(
    newDevice.Id,
    assignCredential: true,
    partNumberName: provider.PartNumber,
    cancellationToken);

Build the new Security Center credential

Build a new Credential entity for the cardholder with the new card number:

var newFormat = provider.GetCredentialFormat(newMobileCredential.CardNumber);
if (newFormat == null)
{
    throw new InvalidOperationException(
        "Provider card format is not supported by GetCredentialFormat.");
}

var builder = engine.EntityManager.GetCredentialBuilder();
builder.SetName($"Mobile - {cardholder.LastName}")
       .SetFormat(newFormat)
       .SetCardholder(cardholder);

builder.Build();

Retire the old mobile ID and entity

Retire the old mobile ID and the old Security Center entity. Optionally remove the old device record from HID Origo:

await client.RevokeId(oldMobileCredentialId, cancellationToken);
engine.DeleteEntity(oldCredentialGuid);
await client.DeleteDevice(oldDeviceId, cancellationToken);

Revoking a mobile credential

Revoke the mobile ID at HID Origo and delete the Security Center Credential entity. Both operations are independent. Perform both to fully retire the credential:

await client.RevokeId(mobileCredential.Id, cancellationToken);
engine.DeleteEntity(credentialGuid);

Note

The Mobile Credential Manager role exposes an Automatically revoke mobile credential on deletion toggle on its Configuration tab (default ON). When this toggle is ON, deleting the Security Center Credential entity triggers HID Origo revocation server-side, and an explicit RevokeId call is harmless but redundant. The setting is server-side only; the SDK cannot read or change it. Calling both operations is safe under either configuration.

To remove the cardholder's mobile user altogether, call DeleteUser. The deletion is asynchronous: the task returns once the operation is queued, and HID Origo finishes removing the user some time after.

await client.DeleteUser(mobileUser.Id, cancellationToken);

DeleteDevice removes a single device from a user without deleting the user.

Inspecting users, devices, and mobile IDs

The mobile credential client exposes lookup methods grouped by what you want to retrieve: users, devices, mobile IDs, invitations, and tenant information. Each lookup returns a read-only type defined in Returned types.

Look up users

Look up a single mobile user by id, or list users by external id (the cardholder GUID). For the no-match behavior of these calls, see Error handling.

var user = await client.GetUser(mobileUserId, cancellationToken);
var usersForCardholder = await client.GetUsers(
    externalId: cardholderGuid.ToString(),
    cancellationToken);

var allUserIds = await client.GetAllUserIds(cancellationToken);
var idsForCardholder = await client.GetUserIds(
    externalId: cardholderGuid.ToString(),
    cancellationToken);

Look up devices

List devices registered for a user, or fetch a single device's details:

var deviceIds = await client.GetUserDevices(mobileUserId, cancellationToken);
var device = await client.GetDevice(deviceIds.First(), cancellationToken);

Look up mobile IDs

List mobile IDs by device, by part number, or filter by status. The maximum count parameter caps the result size:

var mobileIdsForDevice = await client.GetMobileIdsByDevice(
    deviceId, cancellationToken);

var mobileIdsForPartNumber = await client.GetMobileIdsByPartNumber(
    provider.PartNumberId, cancellationToken);

var activeIds = await client.GetActiveMobileIds(
    maxCount: 100, provider.PartNumberId, cancellationToken);

var revokedIds = await client.GetRevokedMobileIds(
    maxCount: 100, provider.PartNumberId, cancellationToken);

var mobileId = await client.GetMobileId(mobileCredentialId, cancellationToken);

Look up an invitation

Retrieve a single invitation by id, including its current Status and ExpirationDate:

MobileInvitation invitation = await client.GetInvitation(
    invitationId, cancellationToken);

Look up part numbers and tenant information

List part numbers and tenant information:

var partNumberIds = await client.GetAllPartNumbers(cancellationToken);
var partNumber = await client.GetPartNumberDetails(
    partNumberIds.First(), cancellationToken);

CustomerInfo info = await client.GetCustomerInfo(cancellationToken);

Returned types

The mobile credential client returns a small set of read-only types. Use these property tables to plan inspection, filtering, and capacity-planning workflows.

MobileCredentialUser:

Property	Type	Description
Id	string	The mobile user id assigned by HID Origo
ExternalId	string	The cardholder GUID supplied at creation
GivenName	string	First name
FamilyName	string	Family name
Emails	IEnumerable<string>	Email addresses on the user record
Status	string	The HID Origo user status
UserInvitations	IEnumerable<MobileInvitation>	Invitations issued for this user
Devices	IEnumerable<MobileCredentialDevice>	Registered devices
UnregisteredCredentials	IEnumerable<MobileCredential>	Card numbers reserved by CreateUser with assignCredential: true but not yet bound to a registered device

MobileInvitation:

Property	Type	Description
Id	string	The invitation id used by SendInvitation, CancelInvitation, and GetInvitation
InvitationCode	string	The code the cardholder enters in the HID Origo app
Status	string	The invitation status
CreatedDate	DateTime	When the invitation was created
ExpirationDate	DateTime	When the invitation expires

MobileCredentialDevice:

Property	Type	Description
Id	string	The device id used by IssueMobileId, GetDevice, and DeleteDevice
Status	string	The device status reported by HID Origo
ApplicationVersion	string	The HID Origo app version on the device
Credentials	IEnumerable<MobileCredential>	Mobile credentials associated with the device

MobileCredential:

Property	Type	Description
Id	string	The mobile credential id used by RevokeId and GetMobileId
Status	string	The mobile credential status (active, revoked, and so on)
PartNumber	string	The part number the credential was issued against
PartNumberFriendlyName	string	The display name of the part number
CardNumber	long	The card number to bind to the Security Center Credential entity
CredentialType	string	The credential type reported by HID Origo

MobileCredentialPartNumber:

Property	Type	Description
Id	string	The part number id
Name	string	The part number name passed to CreateUser, CreateInvitation, and IssueMobileId
FriendlyName	string	The display name of the part number
AvailableQuantity	int	The number of credentials still available against this part number
FacilityCode	string	The facility code configured for the part number
FormatNumber	string	The format identifier configured for the part number

CustomerInfo:

Property	Type	Description
Name	string	The customer name on the HID Origo tenant
Id	string	The customer id
SubscriptionType	string	The HID Origo subscription type
ActiveUsers	int	Number of mobile users currently active on the tenant
PendingInvitations	int	Number of invitations sent but not yet accepted
TotalUsers	int	Total mobile users on the tenant (active plus pending)
License	LicenseInfo	License state for the tenant

LicenseInfo:

Property	Type	Description
Name	string	The license name
PartNumber	string	The part number associated with the license
AvailableQuantity	int	Credentials still available under the license
ConsumedQuantity	int	Credentials already consumed
StartDate	DateTime	License start date
EndDate	DateTime	License end date
State	string	License state

Canceling an invitation

Cancel a pending invitation when a cardholder is no longer expected to register. Pass the invitation id, not the invitation code:

await client.CancelInvitation(invitation.Id, cancellationToken);

Receiving status change notifications

Register a webhook URL to receive HID Origo status change notifications. RegisterForCallback returns the callback id you keep for later updates and unregistration:

string callbackId = await client.RegisterForCallback(
    "https://YOUR-SERVER/mobile-credential-callbacks",
    cancellationToken);

await client.UpdateCallback(
    callbackId,
    "https://YOUR-SERVER/v2/mobile-credential-callbacks",
    cancellationToken);

string registeredUrl = await client.GetCallbackUrl(callbackId, cancellationToken);

await client.UnregisterFromCallback(callbackId, cancellationToken);

Error handling

The IMobileCredentialClient methods are asynchronous and communicate with HID Origo, so any of them can fail: a network error, an authentication failure, an invalid id, or HID Origo rejecting the operation. The credential-builder call in the issuance flow can also fail when no credential format or credential request has been set.

GetUsers returns an empty collection when no user matches the supplied externalId; it does not fail for this case. GetUserIds does not apply the same empty-result handling, so a no-match condition fails instead of returning an empty collection. GetCredentialFormat returns null for unsupported card formats and for the Corporate 1000 formats when CompanyId cannot be parsed as int.

Wrap client calls in a try/catch, and on failure decide whether to retry, report the error to the operator, or fail the issuance flow.

See also

• Connecting to Security Center: Engine setup, authentication, and logging on to Security Center.
• Entities: Entity model and IPartitionSupport.
• Privileges: Privilege types, states, and per-user privilege computation.