Core Concepts

PIN Credentials

Numeric keypad codes for backup and temporary access in 5 minutes

5 mins
Beginner

Related API Endpoints

POST Create credential PUT Update credential

4-8 digit numeric codes entered on keypads to unlock doors. Perfect for backup access, visitors, and temporary credentials.

What Are PIN Credentials?

Numeric codes that people type on keypads at doors. No physical card or phone needed - just memorize the code.

Common uses

•
Backup when card is forgotten
•
Temporary visitor access
•
Shared access (delivery codes)
•
Interior doors where cards aren't practical
•
Remote provisioning (send PIN via email/SMS)

When to Use PINs

Best for

•
Backup credentials alongside cards
•
Short-term visitor access
•
Areas with keypads but no card readers
•
Situations requiring quick, remote credential provisioning
•
Temporary contractors (1-2 days)

Not ideal for

•
High-security areas (can be observed/shared)
•
Areas without keypads
•
Primary credential for high-traffic doors (slower than card scan)
•
Long-term permanent access (cards are more convenient)

Creating PIN Credentials

Request:

bash 
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": 6,
      "value": "******",
      "enabled": true
    }
  }'

Using `"value": "***"`* tells DoorFlow to generate a secure random PIN.

Response:

json 
{
  "id": "cred_xyz789",
  "credential_type_id": 6,
  "value": "247815",
  "enabled": true,
  "person_id": 12345,
  "created_at": "2024-01-15T14:30:00Z"
}

The generated PIN (in this example: 247815) is returned in the response. Send this to the user via email, SMS, or your app.

Why auto-generate?

  • More secure (truly random)
  • Avoids weak PINs like 1234, 0000, 1111
  • Prevents PIN reuse across people
  • No user bias (birthdays, addresses, etc.)

Option B: Specify Custom PIN

Request:

bash 
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": 6,
      "value": "5678",
      "enabled": true
    }
  }'

Security warning: User-chosen PINs tend to be weak. Only use custom PINs when required by business needs.

PIN Format Requirements

  • Length: 4-8 digits (varies by channel configuration)
  • Characters: Numeric only (0-9)
  • Leading zeros: Allowed (e.g., 0123 is valid)
  • Must be unique: No two people can have the same PIN

Examples of valid PINs:

"1234"    - 4 digits
"012345"  - 6 digits with leading zero
"98765432" - 8 digits

Examples of invalid PINs:

"123"     - Too short (minimum 4)
"12AB"    - Letters not allowed
"1234 "   - Spaces not allowed
""        - Empty (use "******" for auto-generation)

Managing PIN Credentials

Disabling a PIN

Temporarily disable without deleting:

bash 
curl -X PUT "https://api.doorflow.com/api/3/people/12345/credentials/cred_xyz789" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "person_credential": {
      "enabled": false
    }
  }'

Use cases

•
Visitor's access period ended
•
PIN was compromised (observed by others)
•
Temporary suspension

Resetting a Forgotten PIN

You cannot change a PIN value. To reset:

  1. Delete the old PIN credential
  2. Create a new PIN credential with "value": "******"
  3. Send the new PIN to the user

Example:

bash 
# 1. Delete old PIN
curl -X DELETE "https://api.doorflow.com/api/3/people/12345/credentials/cred_old" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 2. Create new PIN
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": 6,
      "value": "******",
      "enabled": true
    }
  }'

Best Practices

Security

Always auto-generate PINs:

bash 
# Good
"value": "******"

# Bad (weak, common PINs)
"value": "1234"
"value": "0000"

Require periodic changes: For high-security areas, rotate PINs every 90 days.

Don't share PINs: Each person should have a unique PIN. If multiple people use the same PIN, you can't track individual access in audit logs.

Don't print PINs on visitor badges: Security risk if badge is lost. Send via email/SMS instead.

Operational

Use for temporary access: PINs are perfect for visitors who need access for a day or week.

Provide as backup: Give permanent employees both a card and a PIN backup.

Example workflow:

bash 
# Employee onboarding: Card + PIN backup
# 1. Create card (primary)
POST /api/3/people/12345/credentials
{ "credential_type_id": 5, "value": "1234567890", "enabled": true }

# 2. Create PIN (backup)
POST /api/3/people/12345/credentials
{ "credential_type_id": 6, "value": "******", "enabled": true }

Set expiration for visitors: Use reservations to automatically disable PINs after visitor access period ends.

bash 
# Create visitor with time-limited access
POST /api/3/reservations
{
  "person_id": 12345,
  "start_time": "2024-01-15T09:00:00Z",
  "end_time": "2024-01-15T17:00:00Z"
}

Common Use Cases

Backup Access for Employees

Scenario: Employee forgets card at home.

Solution: They use their backup PIN.

bash 
# Issue PIN as backup
POST /api/3/people/12345/credentials
{
  "credential_type_id": 6,
  "value": "******",
  "enabled": true
}

Short-term Visitor

Scenario: Visitor needs access for 1 day.

Solution: Auto-generate PIN and send via email.

bash 
# Create visitor with PIN
POST /api/3/people
{
  "first_name": "Jane",
  "last_name": "Visitor",
  "email": "jane@example.com"
}

# Issue PIN
POST /api/3/people/{person_id}/credentials
{
  "credential_type_id": 6,
  "value": "******",
  "enabled": true
}

# Email the PIN to jane@example.com
# (Handle in your application code)

Delivery Access

Scenario: Delivery drivers need access to loading dock.

Solution: Create shared "Delivery" PIN that you can rotate periodically.

Note: This violates "unique PIN per person" best practice but is common for delivery access. Be aware you lose individual audit trail.

After-hours Access

Scenario: Employees occasionally need building access outside normal hours.

Solution: Give them a PIN that works during specific time windows via roles.

Monitoring PIN Usage

Check when PINs are being used via events:

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

Response includes which credential was used:

json 
{
  "events": [
    {
      "event_type": "access_granted",
      "person_id": 12345,
      "credential_id": "cred_xyz789",
      "credential_type": "PIN",
      "channel_name": "Front Door",
      "timestamp": "2024-01-15T14:30:00Z"
    }
  ]
}

Look for suspicious patterns

•
PIN used at unusual times
•
PIN used at multiple doors simultaneously (shared PIN)
•
Frequent PIN failures (someone trying to guess)

Common Questions

Can I retrieve a PIN after creation?

A: Yes. Use GET /api/3/people/{person_id}/credentials to see all credentials including PIN values.

Can two people have the same PIN?

A: No. DoorFlow enforces unique PIN values across all people in your account.

How do I reset a forgotten PIN?

A: Delete the old PIN credential and create a new one with auto-generation ("value": "******").

What happens if someone enters the wrong PIN 3 times?

A: Behavior depends on your channel settings. Some channels lock out after multiple failures. Check your hardware documentation.

Can PINs expire automatically?

A: PINs themselves don't expire, but you can use reservations to create time-limited access that automatically disables after a period.

Should I give visitors PINs or cards?

A: PINs for short visits (1 day). Cards for longer visits (1+ weeks) if you have inventory. Mobile credentials for tech-savvy visitors with smartphones.

Quick Reference

Create auto-generated PIN:

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

Create custom PIN:

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

List person's credentials:

bash 
GET /api/3/people/{person_id}/credentials

Disable PIN:

bash 
PUT /api/3/people/{person_id}/credentials/{credential_id}
Body: { "enabled": false }

Delete PIN:

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

Required OAuth scope: account.person (write) or account.person.readonly (read)

Next Steps

Need different credential types?

  • [Card Credentials] - Physical access cards
  • [Mobile Credentials] - Smartphone-based access

Choose the right credential

•
[Credential Comparison] - Compare all types and get recommendations

See it in action

•
[Common Workflows] - Complete examples including PIN issuance for visitors

On this page