Core Concepts

Core Resources Reference

Quick reference for People, Credentials, Channels, Groups, and Roles

5 mins
Beginner

Related API Endpoints

GET List people GET Get person details GET List groups GET List roles GET List channels (door controllers) GET Get channel details

Quick reference for DoorFlow's main resources. Scan to find what you need.

People

Individuals who need building access.

Key Fields

•
id - Unique identifier
•
first_name, last_name - Name
•
email - Contact/identifier
•
enabled - Can they access doors? (true/false)
•
group_ids - Which groups they belong to

Important

•
Creating a person alone doesn't grant access
•
Also need: credentials + group membership
•
Can disable without deleting (preserves audit trail)

Required Scope: account.person (or .readonly for read)

Credentials

Physical or digital tokens that grant access.

Types

•
Card - Physical access card
•
PIN - Keypad code
•
HID Mobile - Bluetooth/NFC phone
•
PassFlow - DoorFlow mobile app

Key Fields

•
id - Unique identifier
•
credential_type_id - What type (5=Card, 6=PIN, etc.)
•
value - Card number / PIN / mobile ID
•
enabled - Currently active? (true/false)
•
person_id - Who owns it

Important

•
One person can have multiple credentials
•
Use "******" for value to auto-generate random PIN
•
Can disable individually

Required Scope: account.person (or .readonly for read)

Channels

Physical access control hardware (the hardware that controls locks).

Key Fields

•
id - Unique identifier
•
name - Human name ("Front Door")
•
mode - Current mode (normal/unlock/lockdown)
•
status - Connection (online/offline)
•
site_id - Which building/location

Modes

•
normal - Standard operation (authorized access only)
•
unlock - Permanently unlocked (anyone can enter)
•
lockdown - Locked for everyone (emergency mode)

Required Scopes

•
Read: account.channel.readonly
•
Admit: account.channel.admit or .admit.person

Groups

Collections of people with similar access needs.

Key Fields

•
id - Unique identifier
•
name - Group name ("Employees", "Visitors")
•
people_count - How many members

Important

•
Groups are linked to Roles to define door access
•
People can belong to multiple groups
•
Access is additive (more groups = more access)

Required Scope: account.group.readonly (read-only)

Note: Can't create/modify groups via API - use web interface

Roles

Define which groups can access which channels (and when).

Key Fields

•
id - Unique identifier
•
name - Role name
•
group_ids - Which groups have this role
•
channel_ids - Which doors it grants access to
•
shift_ids - Optional time restrictions

Important

•
This is where actual permissions are defined
•
One role can apply to multiple groups
•
Can include schedules (e.g., "only during business hours")

Required Scope: account.role.readonly (read-only)

Note: Can't create/modify roles via API - use web interface

Group Reservations

Temporarily assign groups to a person for a specific timeframe. This grants them access to all doors/areas the group has permissions for during that period.

Key Fields

•
id - Unique identifier
•
person_id - Who receives the temporary group membership
•
group_id - Which group to assign them to temporarily
•
start_time - When membership begins (ISO 8601)
•
end_time - When membership expires (ISO 8601)

Important

•
Person gains access to all channels the group has permissions for
•
Person still needs a credential to access doors
•
Works alongside their permanent group memberships (access is additive)
•
Automatically expires after end_time
•
Better than regular reservations when someone needs access to many doors

Common Use Cases

•
Contractor needs building access for duration of 3-month project
•
Temporary employee needs same access as full-time staff for 6 months
•
Consultant needs executive-level access for 2-week engagement
•
Maintenance worker needs facility-wide access during renovation period

Why use this instead of regular reservations?

  • One group reservation grants access to many doors (via group's role permissions)
  • Longer timeframes (weeks/months vs hours/days)
  • Easier to manage than creating individual reservations per door

Required Scope: account.reservation (or .readonly for read)

Events

Audit log of all activity. Read-only.

Key Fields

•
id - Unique identifier
•
event_code - Type of event (10-18=admit, 20-29=reject, etc.)
•
person_id - Who was involved
•
channel_id - Which door
•
occurred_at - Timestamp (UTC)
•
description - Human-readable

Important

•
Events are immutable (can't create/modify/delete)
•
Use for audit trails, attendance, security monitoring
•
Filter by person, channel, time, event type

Required Scope: account.event.access.readonly

Sites

Physical locations/buildings. Read-only.

Key Fields

•
id - Unique identifier
•
name - Location name
•
address - Physical address

Required Scope: account.site.readonly

Quick Decision Guide

Need to grant someone permanent access?

  1. Create Person → Assign to Group → Issue Credential

Need temporary access to many doors (contractor, temp employee)?

  1. Create Person → Issue Credential → Create Group Reservation (assigns them to group temporarily)

Need short-term access to specific doors (visitor)?

  1. Create Person → Issue Credential → Create Regular Reservation (not group reservation)

Need to revoke access?

  • Option 1: Disable person (enabled: false)
  • Option 2: Disable their credentials
  • Option 3: Remove from groups (or delete group reservation for temporary access)

Need to monitor access?

  • Query Events filtered by person/channel/time

Need to lockdown building?

  • POST /channels/{id}/lockdown for each channel

On this page