Quickstart Guide

This guide walks you through the complete workflow for granting someone access to a door using the DoorFlow API. You'll learn about creating people, issuing credentials, and managing access.

What You'll Learn

By the end of this guide, you'll understand:

• How to authenticate with the DoorFlow API
• How to discover your building setup (doors, credential types, groups)
• How to create person records
• How to issue credentials (access cards, PINs)
• How to query the events log
• How to create temporary access reservations

Prerequisites

• A DoorFlow Developer account (sign up here)
• An OAuth application created in the Developer Portal
• An access token from completing the OAuth flow
• Command line access with curl (or similar HTTP client)
• Basic understanding of REST APIs and OAuth 2.0

Getting Your Access Token

Before you can make API calls, you need an access token. Your newly created OAuth application is in "testing" state, which means it's linked to a test DoorFlow account.

Option 1: Try the Interactive Demo (Recommended)

The fastest way to explore the API is through our interactive demo:

1. Go to your OAuth application page in the Developer Portal
2. Click "Get started with the API right now, no coding required"
3. Follow the guided walkthrough

This demo handles OAuth authentication automatically and walks you through API operations step-by-step.

Option 2: Implement OAuth Flow

To get an access token for making API calls directly:

1. On your OAuth application page, find the "OAuth Authorize URL"
2. Visit that URL in your browser (or redirect your users there)
3. Authorize the application
4. You'll be redirected back with an authorization code
5. Exchange the code for an access token:

curl -X POST "https://api.doorflow.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

The response will contain your access_token.

For detailed OAuth instructions, see the OAuth 2.0 Guide.

Step 1: Verify Your Connection

Once you have an access token, confirm authentication works by calling the account endpoint.

Request:

curl -X GET "https://api.doorflow.com/api/3/account" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace YOUR_ACCESS_TOKEN with your token.

What this means: You're successfully authenticated! This endpoint returns your account's basic information.

Step 2: Discover Your Account Setup

Before creating people and credentials, you need to know what doors exist and what credential types are available.

List Your Channels (Doors)

Request:

curl -X GET "https://api.doorflow.com/api/3/channels" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Note the channel IDs - you'll need these later.

List Available Credential Types

Request:

curl -X GET "https://api.doorflow.com/api/3/credential_types" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Note the credential type IDs. You can cache these within your application for use elsewhere as they rarely change for an account.

List Existing Groups

Request:

curl -X GET "https://api.doorflow.com/api/3/groups" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Why do this? Groups are connected to roles that define which doors members can access. By assigning someone to a group, they inherit that group's access permissions.

Step 3: Create a Person

Now let's create a person record who needs building access.

Request:

curl -X POST "https://api.doorflow.com/api/3/people" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "enabled": true,
    "group_ids": [1]
  }'

Important: Replace [1] with the group ID you noted in Step 2.

Save the person ID (e.g., 12345) - you'll need it in the next step.

What you've done: Created a person record and assigned them to a group. However, they still can't access doors because they don't have a credential yet!

Step 4: Issue a Credential

Now let's give Jane a credential - an access card she can use at doors.

Request:

curl -X POST "https://api.doorflow.com/api/3/people/12345/credentials" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_credential": {
      "credential_type_id": 5,
      "value": "1234567890",
      "enabled": true
    }
  }'

Pro tip: If you're issuing a PIN instead, use "value": "******" to auto-generate a random PIN. The response will contain the generated PIN.

What you've done: Jane now has a credential (card #1234567890) and belongs to a group that grants door access. She can now access any doors permitted by her group!

Step 5: Verify Access via Events

Let's check if Jane has used her credential to access any doors.

Request:

curl -X GET "https://api.doorflow.com/api/3/events?last_name=Doe" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If the events array is empty: Jane hasn't used her credential yet, or you don't have access to test with physical hardware. That's okay - the API setup is complete!

Other useful event queries:

# Events for a specific channel
curl -X GET "https://api.doorflow.com/api/3/events?channel_id=1340" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Events from the last hour
curl -X GET "https://api.doorflow.com/api/3/events?since_utc=2024-01-15T13:00:00Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

What you've learned: The events API provides a complete audit trail of all access activity. You can filter by person, channel, time range, or event type.

Step 6: Create a Temporary Access Reservation (Optional)

Reservations grant temporary, time-limited access. Perfect for visitors!

Scenario: Give Jane access to the Front Door for today only, 9 AM to 5 PM.

Request:

curl -X POST "https://api.doorflow.com/api/3/group_reservations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_id": 12345,
    "channel_ids": [1340],
    "start_time": "2024-01-15T09:00:00Z",
    "end_time": "2024-01-15T17:00:00Z",
    "group_ids": [
      1
    ]
  }'

What you've done: Jane can now access the Front Door during that specific time window, even if she wasn't normally granted access via groups/roles.

What You've Learned

Congratulations! You've completed the DoorFlow API quickstart. Here's what you've accomplished:

• Authentication - Obtained an access token via OAuth
• Discovery - Listed channels, credential types, and groups
• Identity Management - Created a person record
• Credential Issuance - Gave someone an access card
• Audit Trail - Queried the events log
• Access Control - Understood groups, roles, and reservations

Common Issues & Solutions

Issue: "Person can't access doors even though I created them and gave them a credential"

Solution: Check these:

• Is the person enabled? (Step 3)
• Is the credential enabled? (Step 4)
• Is the person assigned to a group? (Step 3, group_ids)
• Does that group have a role granting access to the desired channels?
• Is the channel in normal mode (not lockdown)?

Issue: "Getting 403 Forbidden errors"

Solution: Your OAuth application doesn't have the required scope. Edit your application in the Developer Portal and request the missing scope.

Issue: "Events API returns empty array"

Solution: Either no one has accessed doors yet, or you're filtering too restrictively. Try removing filters to see all events: GET /api/3/events

Issue: "Can't find my channel/group IDs"

Solution: List them again using Step 2. Make sure you're using the numeric ID value, not the name.

Next Steps

Now that you've completed the quickstart, deepen your knowledge: