Credentials

Create credential

Creates a new credential for a person. For HID Mobile Access and PassFlow credentials, this initiates an invitation process.

POST /api/3/people/{person_id}/credentials

Authentication

This endpoint requires authentication:

OAuth 2.0 Recommended

Use an OAuth 2.0 access token in the Authorization header. This is the recommended authentication method for all integrations. OAuth provides automatic token expiration, granular permission scopes, detailed usage tracking, and per-integration revocation. Learn how to obtain an access token.

Header Format:

Authorization: Bearer YOUR_ACCESS_TOKEN

Required Scopes:

account.person

Parameters

Path Parameters

person_id integer
Required

Person ID

Request Body

person_credential object
Required
Show child attributes
credential_type_id integer required
eg. 5

ID of the credential type (required)

value string
eg. 1234567890

Credential value (for card numbers, PINs, etc. Use "******" to auto-generate a random PIN)

person_id integer

Person ID (typically derived from URL path parameter)

Example

{
  "person_credential": {
    "credential_type_id": 5,
    "value": "1234567890",
    "person_id": 0
  }
}

Responses

201

Credential created successfully

Response Fields

id string required

Unique hashid identifier for the credential

eg. abc123xyz
credential_type_id integer required

ID of the credential type

eg. 5
label string required

Human-readable label for the credential type

eg. Card Number
person_id integer required

ID of the person this credential belongs to

eg. 12345
value string | null

Credential value (only present for value-assignable credential types like cards, PINs, etc. Not present for mobile credentials)

eg. 1234567890
status string | null

Status for mobile credentials (HID Mobile Access)

eg. active
url string | null

PassFlow credential URL (only for PassFlow credentials in invited state)

wallet_type string | null

Wallet type for PassFlow credentials that have been added to wallet

401

Unauthorized - Invalid or missing authentication

Response Fields

error string
eg. unauthorized
error_description string
eg. The access token is invalid
403

Forbidden - User does not have permission

Response Fields

error string
eg. forbidden
error_description string
eg. You are not authorized to access this resource
409

Conflict - Credential already exists for this credential type

Response Fields

id string required

Unique hashid identifier for the credential

eg. abc123xyz
credential_type_id integer required

ID of the credential type

eg. 5
label string required

Human-readable label for the credential type

eg. Card Number
person_id integer required

ID of the person this credential belongs to

eg. 12345
value string | null

Credential value (only present for value-assignable credential types like cards, PINs, etc. Not present for mobile credentials)

eg. 1234567890
status string | null

Status for mobile credentials (HID Mobile Access)

eg. active
url string | null

PassFlow credential URL (only for PassFlow credentials in invited state)

wallet_type string | null

Wallet type for PassFlow credentials that have been added to wallet

422

Unprocessable Entity - Validation failed

Response Fields

error string

Error message

errors object

Field-specific validation errors

Show child attributes
value array
eg. ["value is already in use on your account", "must be between 4 and 7 digits in length"]

Validation errors for the credential value

credential_type_id array
eg. ["Not found for this account"]

Validation errors for the credential type

limit_reached string
eg. You have reached your HID Mobile licence limit. Please contact DoorFlow Support.

License limit error message

500

Internal Server Error

Response Fields

error string
eg. internal_server_error
error_description string
eg. An unexpected error occurred

Mentioned in Guides

This endpoint is used in the following guides:

Card Credentials

Physical access cards - the most common credential type in 5 minutes

Core Concepts • 5 min • Beginner

PIN Credentials

Numeric keypad codes for backup and temporary access in 5 minutes

Core Concepts • 5 min • Beginner

Mobile Credentials

Smartphone-based access with HID Mobile Access and PassFlow in 5 minutes

Core Concepts • 5 min • Intermediate

Issuing Mobile Passes for HID Mobile Access

Complete workflow for provisioning HID Mobile Access credentials via invitation codes

Core Concepts • 8 min • Intermediate

Issuing PassFlow Mobile Passes for Apple/Google Wallet

Complete workflow for provisioning PassFlow credentials to Apple Wallet and Google Wallet via NFC

Core Concepts • 8 min • Intermediate

Employee Onboarding Workflow

Complete code to onboard new employees with card and PIN in 7 minutes

Common Workflows • 7 min • Intermediate

Visitor Management Workflow

Grant temporary access to visitors with time-limited PINs in 7 minutes

Common Workflows • 7 min • Intermediate

Contractor Temporary Access

Grant time-limited access to contractors for weeks or months in 5 minutes

Common Workflows • 5 min • Intermediate

Request

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

Responses

Credential created successfully

{
  "id": "abc123xyz",
  "credential_type_id": 5,
  "label": "Card Number",
  "person_id": 12345,
  "value": "1234567890",
  "status": "active",
  "url": "string",
  "wallet_type": "string"
}