Credentials

Introduction

Credentials are used to identify individual users of an access control system. PDK supports a wide variety of credentials, including digital credentials that can be distributed through the ProdataKey app or a custom mobile app.

There are three types of credentials:

• Card: a physical credential, such as a proximity card, key fob, sticker, wristband, or QR code.
• Bluetooth: a digital credential that requires users to present their phones to a Bluetooth-enabled reader to gain access.
• Mobile: a digital credential that allows users to control devices remotely through the ProdataKey app or an API request.

Note that digital credentials must be activated using credential invitations.

The credential object

Physical

{
  "id": 1,
  "personId": 1,
  "credentialNumber": 1234567,
  "facilityCode": null,
  "description": null,
  "types": ["card"]
}

Digital

{
  "id": 1,
  "personId": 1,
  "credentialNumber": null,
  "facilityCode": null,
  "description": "Pending",
  "types": ["touch", "token"]
}

Property	Type	Description
id	Integer	The credential ID.
personId	Integer	The credential holder ID.
credentialNumber	Integer	The credential number.
facilityCode	Integer	The facility code number. This only applies to card credentials.
description	String	The credential description.
types	String[]	A list of credential types. Possible values include card for physical credentials, touch for Bluetooth credentials, and token for mobile credentials. Credentials can only be physical or digital, so if card is present in the list, touch and token are ignored.

Basic Endpoints

Create a credential

Request

Physical

POST https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/credentials HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "types": ["card"],
  "credentialNumber": 1234567
}

Digital

POST https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/credentials HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "types": ["touch", "token"],
  "description": "Pending"
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	Integer	Yes	The credential holder ID.
panel_token	Header	String	Yes	A valid panel token.
types	Body	String[]	Yes	A list of credential types. Possible values include card for physical credentials, touch for Bluetooth credentials, and token for mobile credentials. Credentials can only be physical or digital, so if card is present in the list, touch and token are ignored.
credentialNumber	Body	Integer	Sometimes	The credential number. This value is required for card credentials and must be omitted for digital credentials, since it will be set automatically once a digital credential is accepted. This value must be unique among all other credential numbers on the cloud node.
facilityCode	Body	Integer	No	The facility code number. This only applies to card credentials.
description	Body	String	No	The credential description. For digital credentials, this should be initialized to "Pending". Once a digital credential is accepted, this value is set to a description of the associated mobile device and can no longer be changed. The maximum length is 255 characters.

Response

The response contains the ID of the newly created credential object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1
}

Retrieve a credential

Request

GET https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/credentials/{{credential_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	Integer	Yes	The credential holder ID.
credential_id	Path	Integer	Yes	The credential ID.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains a credential object.

Physical

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "personId": 1,
  "credentialNumber": 1234567,
  "facilityCode": null,
  "description": null,
  "types": [
    "card"
  ]
}

Digital

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "personId": 1,
  "credentialNumber": null,
  "facilityCode": null,
  "description": "Pending",
  "types": [
    "touch",
    "token"
  ]
}

Update a credential

Once a credential is created, its properties can't be updated, with the exception of the types property of a digital credential.

Request

PUT https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/credentials/{{credential_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "types": ["touch", "token"]
}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	Integer	Yes	The credential holder ID.
credential_id	Path	Integer	Yes	The credential ID.
panel_token	Header	String	Yes	A valid panel token.
types	Body	String[]	Yes	A list of credential types. Possible values include touch for Bluetooth credentials and token for mobile credentials.

Response

The response contains the ID of the updated credential object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1
}

Delete a credential

Request

DELETE https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/credentials/{{credential_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	Integer	Yes	The credential holder ID.
credential_id	Path	Integer	Yes	The credential ID.
panel_token	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

List all credentials

Request

GET https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/credentials HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
panel_id	Path	String	Yes	The cloud node serial number.
person_id	Path	Integer	Yes	The credential holder ID.
panel_token	Header	String	Yes	A valid panel token.

Response

The response contains an array of credential objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "personId": 1,
    "credentialNumber": 1234567,
    "facilityCode": null,
    "description": null,
    "types": [
      "card"
    ]
  },
  {
    "id": 2,
    "personId": 1,
    "credentialNumber": null,
    "facilityCode": null,
    "description": "Pending",
    "types": [
      "touch",
      "token"
    ]
  }
]

Credential Invitations

After a digital credential is created, it must then be accepted from the user's mobile device. This process is initiated by using the REST API to send an invitation, which can then be accepted in the ProdataKey app or a custom mobile app.

Create a credential invitation

Request

POST https://accounts.pdk.io/api/credentials/people HTTP/1.1
Authorization: Bearer {{id_token}}
Content-Type: application/json

{
  "panelId": "{{panel_id}}",
  "personId": {{person_id}},
  "credentialId": {{credential_id}},
  "types": ["touch", "token"]
}

Parameter	Location	Type	Required	Description
id_token	Header	String	Yes	A valid ID token.
panel_id	Body	String	Yes	The cloud node serial number.
person_id	Body	Integer	Yes	The credential holder ID.
credentialId	Body	Integer	Yes	The credential ID.
types	Body	String[]	Yes	A list of credential types. Possible values include touch for Bluetooth credentials and token for mobile credentials.
email	Body	String	No	The credential holder's email address. If this parameter is defined, an invitation with PDK branding will be sent to the specified email address. For custom branding, you can omit this parameter and send an invitation directly from your application.

Response

The response contains an inviteId, which can be used to send custom-branded activation emails (note that this only applies if the email parameter is defined).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "inviteId": "644f663819a2920001769622"
}

If you'd like the recipients of your custom-branded emails to activate credentials using the ProdataKey app, use the following deep link format.

https://doors.pdk.io/invite/{{inviteId}}

If you'd like the recipients of your custom-branded emails to activate credentials using your custom app, be sure to include the inviteId in your deep link. The inviteId can then be passed to the iOS SDK or Android SDK for activation.

https://example.com/activate?inviteId={{inviteId}}

Delete a credential invitation

Request

DELETE https://accounts.pdk.io/api/credentials/people HTTP/1.1
Authorization: Bearer {{id_token}}
Content-Type: application/json

{
  "panelId": "{{panel_id}}",
  "credentialId": {{credential_id}}
}

Parameter	Location	Type	Required	Description
id_token	Header	String	Yes	A valid ID token.
panel_id	Body	String	Yes	The panel ID.
credential_id	Body	Integer	Yes	The credential ID.

Response

HTTP/1.1 204 No Content

Credential Self-Help

Organizations can reduce administrative load by enabling credential self-help, which allows users to reset their digital credentials on a new mobile device (e.g. when they get a new phone). However, in order to prevent abuse, the ability to reset credentials is restricted after a certain number of requests (the default limit is 1 request per month). The endpoints below allow you to manage any self-help restrictions that are currently in force.

List all credential self-help restrictions

Request

GET https://accounts.pdk.io/api/credentials/people/restrictions?panel_id={{panel_id}} HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
panel_id	Query	String	Yes	The panel ID.
person_id	Query	Integer	No	The person ID.
id_token	Header	String	Yes	A valid ID token.

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "panelId": "1234ABC",
    "personId": 1,
    "credentialId": 1
  }
]

Clear all credential self-help restrictions

Request

GET https://accounts.pdk.io/api/credentials/people/restrictions/clear HTTP/1.1
Authorization: Bearer {{id_token}}
Content-Type: application/json

{
  "panelId": "1234ABC",
  "personId": 1
}

Parameter	Location	Type	Required	Description
id_token	Header	String	Yes	A valid ID token.
panel_id	Body	String	Yes	The panel ID.
person_id	Body	Integer	Yes	The person ID.

Response

HTTP/1.1 204 No Content