Getting Started

Choosing the Right Scopes

Select the right OAuth scopes for your application

5 mins
Beginner

Scopes define the level of access your application has to a DoorFlow account. When requesting authorization, you must specify which scopes your application needs.

Understanding Scopes

Required scopes: You must request at least one scope to authenticate. Choose only the scopes you need for your integration to function.

Optional scopes: Request additional scopes as your integration's needs grow. Users will need to re-authorize when you add new scopes.

Best practice: Start with minimal scopes. Users are more likely to authorize apps that request fewer permissions.

Available Scopes

People & Credentials

Scope Access Description Provides Access To
account.person.readonly Read View people and their assigned credentials Person details, group membership, credential assignments
account.person Read/Write Create, update, and delete people. Issue and revoke all credential types (cards, PINs, mobile credentials) All person management operations including credential issuance
account.credential_type.readonly Read View available credential type configurations Credential type list and settings

Note: Credentials are managed through person endpoints. The account.person scope includes all credential operations.

Channels (Doors)

Scope Access Description Provides Access To
account.channel.readonly Read View channels and their current status Channel details, online/offline status, mode settings
account.channel.admit Write Remotely unlock any channel without person context Unrestricted remote unlock capability
account.channel.admit.person Write Unlock channels for specific people with audit trail Person-specific remote unlock operations

Critical: account.channel.admit is a restricted scope requiring DoorFlow approval. Use account.channel.admit.person when possible for better security and audit trails.

Events & Audit

Scope Access Description Provides Access To
account.event.access.readonly Read View access events and activity history Access attempts (successful and failed), timestamps, event details

Note: Events are always read-only. They cannot be created or modified via API.

Access Control

Scope Access Description Provides Access To
account.group.readonly Read View groups and their members Group details and membership lists
account.role.readonly Read View role assignments (which groups access which channels) Role configurations and access mappings
account.reservation Read/Write Create and manage time-limited access grants Temporary access scheduling

Note: Group and role write operations are not currently available via API. Manage these through the DoorFlow web interface.

Sites & Locations

Scope Access Description Provides Access To
account.site.readonly Read View physical sites and locations Site details and organization structure

Adding Scopes to Existing Apps

When you need to add scopes to an existing OAuth application:

  1. Update OAuth application in Developer Portal with new scopes
  2. DoorFlow reviews request (1-2 business days for approved/live apps)
  3. Existing users re-authorize to grant new permissions
  4. Handle mixed states where some users have new scopes, others don't

Migration strategy: Check granted scopes in token response and gracefully degrade features for users who haven't re-authorized yet.

Restricted Scopes

Some scopes require special approval due to security implications:

Scope Restriction Reason Approval Process
account.channel.admit Allows unrestricted door unlock without audit trail Requires demonstrating use case not achievable with account.channel.admit.person

When requesting restricted scopes, provide detailed justification in your OAuth application description.

On this page