Getting started

Endpoints

General

Credentials

A Person defines an access control participant. People represent real world users of the access control system.

When creating or updating a person you can provide the pin number as ****** and a unique random pin will be generated.

A Credential always belongs to a Person.

Before making changes to credentials, be sure to understand Credential Types

Listing credentials for a Person

Scopes required : account.person or account.person.readonly

Returns a list of all credentials for a person.

GET /api/3/people/:person_id/credentials

Example Response

[
    {
        "id": "R1sRdPO",
        "credential_type_id": 3,
        "label": "Pin",
        "person_id": 2,
        "value": "1266"
    },
    {
       "id": "Q6sRrQO",
        "person_id": 2,
        "credential_type_id": 14,
        "label": "PassFlow Mobile Access",
        "status": "invited",
        "url": "https://redeem.passflow.io/passes/5wUXbsX"
    },
    {
        "id": "OQso5Q1",
        "person_id": 2,
        "credential_type_id": 14,
        "label": "HID Mobile Access",
        "status": "invited",
        "invitation_code": "AGEW-54UE-WRQQ-ATFA",
        "invitation_expires_at": "2022-08-06T21:51:52+01:00"
    }
]

Remember that this endpoint might be paginated

PassFlow Credential Type Attributes

Status Field

The status field can have two possible values:

Status Description
invited Initial state when the pass is created
added_to_wallet State after user has added the pass to their digital wallet

Additional Fields

For more information on the importance of treating the 'url' field securely please look at our best practices for secure pass distribution

Depending on the status, additional fields will be present:

Status Field Description
invited url Redemption URL for adding pass to wallet. This URL:
• Acts as a bearer token
• Should only be shown to authenticated users
• Must not be stored in databases
• Should be treated as sensitive data
Important: Never log this URL or expose it to unauthorized systems or users.
Implement strict audit logs to track URL access.
added_to_wallet wallet_type Type of wallet containing the pass:
• Can be "apple" or "google"

Example Responses

When first created:

{
    "id": "Q6sRrQO",
    "person_id": 2,
    "credential_type_id": 14,
    "label": "PassFlow Mobile Access",
    "status": "invited",
    "url": "https://redeem.passflow.io/passes/5wUXbsX"
}

After added to wallet:

{
    "id": "Q6sRrQO",
    "person_id": 2,
    "credential_type_id": 14,
    "label": "PassFlow Mobile Access",
    "status": "added_to_wallet",
    "wallet_type": "apple"
}

Status Transitions

  • The status field transitions from invited to added_to_wallet when the pass is successfully redeemed by the user.
  • This transition is managed automatically by PassFlow after the redemption URL is used.

When a pass is added/removed from a wallet this will trigger webhooks for all applications linked to the account using OAuth with a valid access or refresh_token (and the correct scopes as outlined on the webhooks documentation).

Retrieve a credential

Scopes required : account.person or account.person.readonly

You can call a single person's record by passing the id of the record in the URL:

GET /api/3/credentials/:id

Example Response

 {
    "id": "Q6sRrQO",
    "person_id": 2,
    "credential_type_id": 14,
    "label": "PassFlow Mobile Access",
     "status": "invited",
     "url": "https://redeem.passflow.io/passes/5wUXbsX"
}

Create a credential

Scopes required : account.person

POST /api/3/credentials

Example POST data

{
    "person_id": 2,
    "credential_type_id": 28,
    "value": "1234"
}

Example Response

[
    {
        "id": "R1sRdPO",
        "credential_type_id": 1234,
        "label": "Pin",
        "person_id": 2,
        "value": "1234"
    }
]

Only person_id and credential_type_id is required. Value is not used when creating an HID Mobile, Apple or Google credential.

Note that the credential_type_ids you can use are defined in the credential_types endpoint

Each DoorFlow person record may only use a credential_type_id once, if you attempt to create a credential using an already used credential_type_id then the existing credential_type_id will be returned.

Creation or update of a credential will trigger webhooks for all applications linked to the account using OAuth with a valid access or refresh_token (and the correct scopes as outlined on the webhooks documentation).

Creating a mobile access credential

Scopes required : account.person

A mobile access credential could be provided by HID Mobile, Apple iOS or Google Wallet. You can determine which credential_type_id can use are defined in the /credential_types endpoint

POST /api/3/credentials

Example POST data

{
    "person_id": 2,
    "credential_type_id": 14
}

Any value that is passed when creating a mobile access credential will be ignored.

Example Response

 {
    "id": "Q6sRrQO",
    "person_id": 2,
    "credential_type_id": 14,
    "label": "PassFlow Mobile Access",
     "status": "invited",
     "url": "https://redeem.passflow.io/passes/5wUXbsX"
}

Update a credential

Scopes required : account.person

No required parameters.

PUT /api/3/credentials/:id

Note that you cannot change the credential_type_id for an existing credential_type. To do this you will need to delete the existing credential and create a new credential.

The only attribute you can update is the value parameter. Some credentials cannot be updated in this manner - for example mobile access credentials.

Example PUT data

{
    "value": "1234"
}

Delete a credential

Scopes required : account.person

DELETE /api/3/credential/:id

  • Deleting a credential will return a 204 no content status code.
  • Deleting a HID credential with a "invited" status will return a 202 accepted status code.

Invite person to HID Mobile Access

HID Mobile Access is a service that allows anyone with a linked DoorFlow account to gain access to doors on DoorFlow enabled sites via a mobile device.

HID Mobile Access must be enabled for your account, for the following to work properly.

You can invite a DoorFlow person to HID Mobile Access by creating a new credential with the credential_type_id defined in the credential_types endpoint.

Invitation: DoorFlow sends the invitation

By default DoorFlow will distribute the invitation code to the email address on the DoorFlow person record.

Please note that a valid email address must be entered in the email field of a DoorFlow Person for the invite to be successful

POST /api/3/people/:person_id/credentials

Example Response

[
    {
        "id": 9900000180,
        "person_id": 2,
        "credential_type_id": 4321,
        "label": "HID Mobile Access",
        "status": "invited"
    }
]

Invitation: You send the invitation

You however might want to distribute the invitation code yourself and there will be no invitation email from DoorFlow.

This can be set at an account level by contacting DoorFlow.

POST /api/3/people/:person_id/credentials

Example Response

[
    {
        "id": 9900000180,
        "person_id": 2,
        "credential_type_id": 4321,
        "label": "HID Mobile Access",
        "status": "invited",
        "invitation_code": "AGEW-54UE-WRQQ-ATFA",
        "invitation_expires_at": "2022-08-06T21:51:52+01:00"
    }
]

Upon creating an HID Mobile Access credential you will be returned invitation_code and invitation_expires_at. You can then distribute the invitation_code to the person who can then

Note: Once an invitation_code has been used on the HID Mobile Access iOS or Android app the DoorFlow credential object will be deleted and a new credential object will be created with a status: "active"

POST /api/3/people/:person_id/credentials

Example Response

[
    {
        "id": 1001,
        "person_id": 2,
        "credential_type_id": 4321,
        "label": "HID Mobile Access",
        "status": "active"
    }
]

For more information about HID Mobile Access, please drop an email to api@doorflow.com

In this article