Core Concepts

Issuing Mobile Passes for HID Mobile Access

Complete workflow for provisioning HID Mobile Access credentials via invitation codes

8 mins
Intermediate

Related API Endpoints

POST Create credential

This guide focuses on the complete workflow for issuing HID Mobile Access passes for Bluetooth Low Energy (BLE) access.

Other pass types can be issued using similar methods:

  • Issuing HID Mobile Access passes for Apple/Google Wallet
  • Issuing PassFlow mobile passes for Apple/Google Wallet
  • Issuing Apple Access mobile passes

Overview

HID Mobile Access uses an invitation-based workflow where:

  1. An admin requests a mobile credential for a person
  2. DoorFlow creates an invitation code via HID Origo
  3. The invitation code is sent to the person (via email or API)
  4. The person accepts the invitation in the HID Mobile Access app
  5. HID Origo provisions the credential to their device
  6. The credential syncs with DoorFlow's access control channels

All interaction with HID services is handled by DoorFlow to ensure a consistent flow for all credential types.

Sequence Diagram

This diagram shows two approaches - pass issuance triggered from the DoorFlow UI and pass issuance triggered via the API:

sequenceDiagram participant Admin as DoorFlow Admin User participant ClientApp as Client App participant DoorFlow as DoorFlow participant HIDOrigo as HID Origo participant HIDSDK as HID Mobile SDK participant Person as Person Note over Admin,Person: [1. Request HID Mobile Access for Person] alt Request via DoorFlow UI Admin->>DoorFlow: 1a. Request via website else Request via API ClientApp->>DoorFlow: 1b. Request via API end DoorFlow->>Admin: 1b. Return credential_id with status 'invited' DoorFlow->>HIDOrigo: 2. Create user invitation code HIDOrigo-->>DoorFlow: 3. Return invitation code Note over ClientApp,Person: [4. Invitation code sent via API or email] alt Configured at DoorFlow account level DoorFlow->>Person: 4a. Send invitation code via Email else Developer handles delivery ClientApp->>DoorFlow: 4b. Request details for credential_id DoorFlow-->>ClientApp: 4b. Return invitation code for credential_id ClientApp->>Person: 4a. Send invitation code via Email end Note over Person: [5. Accept invitation code] Person->>HIDSDK: 5a. Input invitation code provided by email alt Take invitation code from API when user confirms acceptance of pass Person->>ClientApp: 5b. Take invitation code from API when user confirms acceptance of pass ClientApp->>HIDSDK: 5b. Input invitation code end HIDSDK->>HIDOrigo: 6. Verify acceptance of invitation code HIDOrigo-->>HIDSDK: 7. Confirmation or rejection HIDSDK->>DoorFlow: 8. Notify invitation code used and credential created DoorFlow->>ClientApp: 4b. Webhook to indicate change of status for credential_id DoorFlow->>HIDOrigo: 9. Sync credential with access channels Note over Admin,Person: [10. DoorFlow Admin removes HID Mobile Access credential] Admin->>DoorFlow: 10a. Remove HID Mobile Access credential ClientApp->>DoorFlow: 10b. Request via API DoorFlow->>HIDOrigo: Revoke credential HIDOrigo->>HIDSDK: Notify credential revoked HIDSDK->>Person: Pass removed DoorFlow->>ClientApp: Webhook to notify of credential status 'revoking' DoorFlow->>ClientApp: Webhook to notify of credential status 'revoked' DoorFlow->>HIDOrigo: Remove credential from DoorFlow

Key Participants

  • Person - The end user receiving access
  • HID Mobile SDK - Resides inside the app being used for access (HID Mobile Access app or 3rd party app with HID Mobile Access SDK)
  • HID Origo - HID's service infrastructure responsible for provisioning credentials to the SDK
  • DoorFlow - The access control platform managing connections between all parties
  • Client App - Your application that integrates with DoorFlow
  • DoorFlow Admin UI - Interface for customer staff to manage access control

Implementation Approaches

Approach 1: DoorFlow Handles Email Delivery

DoorFlow automatically emails the invitation code to the person.

Configuration

•
Set up at DoorFlow account level
•
Person must have email address in DoorFlow

When to use

•
Simple, hands-off implementation
•
You don't need to customize invitation messaging
•
Person already exists in DoorFlow with email

API Flow:

bash 
# 1. Create person (if not exists)
POST /api/3/people
{
  "person": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "enabled": true
  }
}

# 2. Create HID Mobile Access credential
POST /api/3/people/{person_id}/credentials
{
  "person_credential": {
    "credential_type_id": 8,
    "enabled": true
  }
}

# Response includes credential_id with status 'invited'
# DoorFlow automatically emails invitation code to jane@example.com

Approach 2: Your App Handles Delivery

You retrieve the invitation code and send it via your own channels.

When to use

•
Custom invitation messaging
•
Multi-channel delivery (SMS, in-app, etc.)
•
Integration with existing user communication systems
•
You want full control over timing and content

API Flow:

bash 
# 1. Create person (email optional)
POST /api/3/people
{
  "person": {
    "first_name": "Jane",
    "last_name": "Smith",
    "enabled": true
  }
}

# 2. Create HID Mobile Access credential
POST /api/3/people/{person_id}/credentials
{
  "person_credential": {
    "credential_type_id": 8,
    "enabled": true
  }
}

# 3. Retrieve invitation code
GET /api/3/people/{person_id}/credentials/{credential_id}

# Response includes invitation_code field
{
  "id": "cred_abc123",
  "credential_type_id": 8,
  "status": "invited",
  "invitation_code": "ABC-DEF-GHI-JKL",
  "person_id": 12345
}

# 4. Send invitation code via your preferred method
# - Email via your email service
# - SMS via your SMS provider
# - In-app notification
# - QR code display

Credential Status Lifecycle

HID Mobile Access credentials go through several statuses:

  1. invited - Invitation code created, waiting for person to accept
  2. provisioning - Person accepted invitation, credential being provisioned to device
  3. active - Credential successfully provisioned and working
  4. revoking - Revocation requested, being removed from device
  5. revoked - Credential removed from device and DoorFlow

Monitor via webhooks:

json 
{
  "event": "credential.status_changed",
  "credential_id": "cred_abc123",
  "person_id": 12345,
  "old_status": "invited",
  "new_status": "active",
  "timestamp": "2024-01-15T14:30:00Z"
}

Person Acceptance Flow

Using HID Mobile Access App

  1. Person receives invitation code (via email or your app)
  2. Opens HID Mobile Access app
  3. Enters invitation code
  4. App contacts HID Origo to verify code
  5. Credential provisioned to device
  6. DoorFlow receives notification of successful provisioning
  7. Access granted at physical doors

Using Your Custom App (with HID SDK)

If you've integrated the HID Mobile Access SDK into your own app:

  1. Person opens your app
  2. App displays invitation code or prompts user to accept
  3. Your app calls HID SDK with invitation code
  4. SDK provisions credential to device
  5. Rest of flow is the same

Best Practices

Always Monitor Credential Status

Don't assume invitation was accepted. Monitor status changes:

bash 
# Poll for status changes
GET /api/3/people/{person_id}/credentials/{credential_id}

# Or better: Use webhooks
POST /api/3/webhooks
{
  "url": "https://your-app.com/webhooks/doorflow",
  "events": ["credential.status_changed"]
}

Set Expiration for Invitations

If invitation isn't accepted within reasonable time (e.g., 7 days):

  • Send reminder
  • Resend invitation
  • Contact person directly
  • Consider alternative credential type

Provide Clear Instructions

When delivering invitation codes, include:

  • What app to download (HID Mobile Access or your custom app)
  • Where to enter the code
  • Expected timeline (usually provisions in seconds)
  • Who to contact if issues arise
  • Backup access method (PIN) in case of problems

Handle Revocation Properly

When removing HID Mobile Access credentials:

bash 
# Delete credential
DELETE /api/3/people/{person_id}/credentials/{credential_id}

# Credential enters 'revoking' status
# Wait for 'revoked' webhook before confirming to user
# This ensures pass is removed from device

Troubleshooting

Credential stuck in 'invited' status

Person hasn't accepted invitation. Check:

  • Did they receive the invitation code?
  • Do they have the correct app installed?
  • Is the invitation code still valid?
  • Did they enter it correctly?

Credential stuck in 'provisioning' status

Provisioning process interrupted. Options:

  • Wait 5-10 minutes and check again
  • Person should restart HID Mobile Access app
  • Check HID Origo service status
  • Contact DoorFlow support if persists

Credential status 'active' but not working at doors

Credential provisioned but not synced to readers:

  • Check person has group membership with door access
  • Verify person is enabled (enabled: true)
  • Check reader is online and supports HID Mobile Access
  • Wait a few minutes for credential sync to complete
  • Check DoorFlow events for rejected access attempts

Person got new phone, how to transfer credential?

Cannot transfer mobile credentials between devices:

  1. Revoke old credential
  2. Issue new invitation for new device
  3. Person accepts on new device
bash 
# 1. Delete old credential
DELETE /api/3/people/{person_id}/credentials/{old_credential_id}

# 2. Create new credential
POST /api/3/people/{person_id}/credentials
{
  "person_credential": {
    "credential_type_id": 8,
    "enabled": true
  }
}

Security Considerations

Invitation Code Delivery

Invitation codes are sensitive:

  • Treat like temporary passwords
  • Use secure delivery channels (encrypted email, HTTPS API)
  • Don't log invitation codes
  • Expire unused invitations after reasonable time

Webhook Verification

Always verify webhook signatures to ensure requests are from DoorFlow:

javascript 
// Example webhook verification
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Quick Reference

Create HID Mobile Access credential:

bash 
POST /api/3/people/{person_id}/credentials
Body: {
  "credential_type_id": 8,
  "enabled": true
}

Retrieve invitation code:

bash 
GET /api/3/people/{person_id}/credentials/{credential_id}
# Returns: { "invitation_code": "ABC-DEF-GHI-JKL", "status": "invited" }

Check credential status:

bash 
GET /api/3/people/{person_id}/credentials/{credential_id}
# Returns: { "status": "invited|provisioning|active|revoking|revoked" }

Revoke credential:

bash 
DELETE /api/3/people/{person_id}/credentials/{credential_id}

Required OAuth scope: account.person

On this page