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 allows users to gain access by presenting a mobile device to a Bluetooth reader.
• Mobile: a digital credential that allows users to gain access by pressing a button in the ProdataKey app or a custom mobile app.

The credential object

Physical

{
  "id": "83481691-680a-4d8d-9352-9651d3f1753b",
  "holderId": "3a1d8a29-efb3-44cf-94f2-8acbb4acf728",
  "credentialNumber": 1234567,
  "facilityCode": null,
  "description": null,
  "types": ["card"]
}

Digital

{
  "id": "83481691-680a-4d8d-9352-9651d3f1753b",
  "holderId": "3a1d8a29-efb3-44cf-94f2-8acbb4acf728",
  "credentialNumber": null,
  "facilityCode": null,
  "description": null,
  "types": ["touch", "token"]
}

Property	Type	Description
id	String	The credential ID.
holderId	String	The holder ID.
credentialNumber	Integer	The credential number.
facilityCode	Integer	The facility code number. This only applies to card credentials.
description	String	The credential description. For digital credentials that have been activated, this value is set to a description of the associated mobile device.
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://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/credentials HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

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

Digital

POST https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/credentials HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

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

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
system_token	Header	String	Yes	A valid system 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. This value is only configurable for card credentials. The maximum length is 255 characters.
sendEmail	Body	Boolean	No	Whether or not to send a ProdataKey app activation email. This only applies to digital credentials. The default value is true. If set to false, the activation process must be handled by the partner application using the inviteId provided in the response.

Response

Physical

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

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

{
  "id": "83481691-680a-4d8d-9352-9651d3f1753b"
}

Digital

The response contains the ID of the newly created credential object along with an inviteId, which can be used to send custom-branded activation emails (note that this only applies if sendEmail is set to false).

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

{
  "id": "83481691-680a-4d8d-9352-9651d3f1753b",
  "inviteId": "651da6b9340a24e82b824a2a"
}

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}}

Retrieve a credential

Request

GET https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/credentials/{{credential_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
credential_id	Path	String	Yes	The credential ID.
system_token	Header	String	Yes	A valid system token.

Response

The response contains a credential object.

Physical

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

{
  "id": "83481691-680a-4d8d-9352-9651d3f1753b",
  "holderId": "3a1d8a29-efb3-44cf-94f2-8acbb4acf728",
  "credentialNumber": 1234567,
  "facilityCode": null,
  "description": null,
  "types": ["card"]
}

Digital

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

{
  "id": "83481691-680a-4d8d-9352-9651d3f1753b",
  "holderId": "3a1d8a29-efb3-44cf-94f2-8acbb4acf728",
  "credentialNumber": null,
  "facilityCode": null,
  "description": null,
  "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://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/credentials/{{credential_id}} HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

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

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
credential_id	Path	String	Yes	The credential ID.
system_token	Header	String	Yes	A valid system 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": "83481691-680a-4d8d-9352-9651d3f1753b"
}

Delete a credential

Request

DELETE https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/credentials/{{credential_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
credential_id	Path	String	Yes	The credential ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

List all credentials

Request

GET https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/credentials HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
page	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
per_page	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
system_token	Header	String	Yes	A valid system token.

Response

The response contains an array of credential objects.

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

[
  {
    "id": "83481691-680a-4d8d-9352-9651d3f1753b",
    "holderId": "3a1d8a29-efb3-44cf-94f2-8acbb4acf728",
    "credentialNumber": 1234567,
    "facilityCode": null,
    "description": null,
    "types": [
      "card"
    ]
  },
  {
    "id": "07a462bd-d633-4506-a753-2f878d6b6e61",
    "holderId": "3a1d8a29-efb3-44cf-94f2-8acbb4acf728",
    "credentialNumber": null,
    "facilityCode": null,
    "description": null,
    "types": [
      "touch",
      "token"
    ]
  }
]

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/holders/restrictions HTTP/1.1
Authorization: Bearer {{id_token}}

Parameter	Location	Type	Required	Description
id_token	Header	String	Yes	A valid ID token.
systemId	Query	String	Yes	The system ID.
holderId	Query	String	Yes	The holder ID.

Response

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

[
  {
    "holderId": "asefsef-58bf-4513-a5c2-58d352cf7fc3",
    "systemId": "asdfsef-68e9-4718-ab64-cd9dd64338bc",
    "credentialId": "fe5f3wefasef-8263-4a3a-b508-dc56813e0seff"
  }
]

Clear all credential self-help restrictions

Request

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

{
  "systemId": "{{system_id}}",
  "holderId": "{{holder_id}}",
  "credentialId": "{{credential_id}}"
}

Parameter	Location	Type	Required	Description
id_token	Header	String	Yes	A valid id token.
systemId	Body	String	Yes	The system ID.
holderId	Body	String	Yes	The holder ID.
credentialId	Body	String	No	The credential ID.

Response

HTTP/1.1 204 No Content