Applications (CardAuth) REST API

The Application/CardAuth endpoint allows creating and managing all the definitions (device type, credential type and authentication policy) required for contactless card authentication.

Note: To use the version-specific parameters/attributes, you must add api-version=N to the query parameter (that is, first digit only, for example, POST /scim/{tenant}/v2/Users?api-version=10).

The API version supported by HID Authentication Service is 10.3.0.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/configuration/{tenant}/v2/Application/CardAuth	Retrieve the list of all CardAuth Applications
GET	Read	/configuration/{tenant}/v2/ Application/CardAuth /{uid}	Retrieve a CardAuth Application
POST	Create	/configuration/{tenant}/v2/ Application/CardAuth	Create a CardAuth Application
DELETE	Delete	/configuration/{tenant}/v2/ Application/CardAuth /{uid}	Delete a CardAuth Application

Get All CardAuth Applications

GET /Application/CardAuth

Copy

Sample Request URI

GET /configuration/{tenant}/v2/Application/CardAuth

Copy

Sample Request

GET /configuration/{tenant}/v2/Application/CardAuth

Copy

Sample Response

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "resources": [
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:application:CardAuth"],
            "id": "APP_CARD",
            "meta": {
                "resourceType": "Card Auth Application",
                "location": "https://[base-server-url]/scim/tenant/v2/Application/CardAuth/APP_CARD",
                "version": "1"
            },
            "name": "MiFare cards application",
            "notes": "Application for MiFare 1K Contactless Writable cards",
            "type": [ "MIFARE Classic", "Seos" ],
            "deviceType": {
                "devicetypeId": "APP_CARD_DT_CARD",
                "name": "Contactless Card Device",
                "notes": "Generic device for contactless cards",
                "maximumDevicePerUser": 5
            },
            "authenticatorPolicy": {
                "authenticatorPolicyId": "APP_CARD_AT_CARD",
                "disableThreshold": 5,
                "defaultExpiryThreshold": -1,
                "sessionTimeout": 3600000,
                "sessionValidPeriod": 86400000,
                "disabledTimeReset": 0,
                "levelOfAssurance": "urn:hidaaas:policy:at_card"
            }
        }
    ]
}

Get a CardAuth Application

GET /Application/CardAuth/{uid}

where {uid} is the application id.

Copy

Sample Request

GET /configuration/{tenant}/v2/Application/CardAuth/APP_CARD

Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:application:CardAuth"],
    "id": "APP_CARD",
    "meta": {
        "resourceType": "Card Auth Application",
        "location": "https://[base-server-url]/scim/tenant/v2/Application/CardAuth/APP_CARD",
        "version": "1"
    },
    "name": "MiFare cards application",
    "notes": "Application for MiFare 1K Contactless Writable cards",
    "type": [ "MIFARE Classic", "Seos" ],
    "deviceType": {
        "devicetypeId": "APP_CARD_DT_CARD",
        "name": "Contactless Card Device",
        "notes": "Generic device for contactless cards",
        "maximumDevicePerUser": 5
    },
    "authenticatorPolicy": {
        "authenticatorPolicyId": "APP_CARD_AT_CARD",
        "disableThreshold": 5,
        "defaultExpiryThreshold": -1,
        "sessionTimeout": 3600000,
        "sessionValidPeriod": 86400000,
        "disabledTimeReset": 0,
        "levelOfAssurance": "urn:hidaaas:policy:at_card"
    }
}

Create a CardAuth Application

POST /Application/CardAuth

Copy

Sample Request URI

POST /configuration/{tenant}/v2/Application/CardAuth

Attributes for compatible applications are:

Attribute	Description
id	The unique identifier of the application (optional) If not set, an ID is generated by the back end and will be returned in the response If set, it must be unique or an error will be returned (HTTP 409) It will be used to create the IDs for the application's authentication policy and device type
type	The identifiers of the card technologies to allow during enrollment and authentication (optional) If not present, any card can be used If present but empty, no cards can be used
deviceType	name and notes - descriptions for the device type (optional) maximumDevicePerUser - (optional) maximum number of this type of device that can be assigned to a user (default value is 5)
authenticatorPolicy	disableThreshold - (optional) maximum number of successive failures before disabling/locking the authenticator (default value is 5) defaultExpiryThreshold - (optional) maximum number of usage of the authenticator (default value is -1) sessionTimeout - (optional) session inactivity timeout (default value is 3600000 milliseconds) sessionValidPeriod - (optional) session validity (default value is 86400000 milliseconds) disabledTimeReset - (optional) auto unblock of the authenticator (default value is 0) levelOfAssurance - (optional) level of authenticator / ACR value (default value is urn:hidaaas:policy:<at_id> where <at_id> is the authenticatorPolicy ID in lowercase)

Copy

Sample Request

{
    "id": "APP_CARD",
    "name": "MiFare cards application",
    "notes": "Application for MiFare 1K Contactless Writable cards",
    "type": [ "MIFARE Classic", "Seos" ],
    "deviceType": {
        "name": "Contactless Card Device",
        "notes": "Generic device for contactless cards",
        "maximumDevicePerUser": 5
    },
    "authenticatorPolicy": {
        "disableThreshold": 5,
        "defaultExpiryThreshold": -1,
        "sessionTimeout": 3600000,
        "sessionValidPeriod": 86400000,
        "disabledTimeReset": 0,
        "levelOfAssurance": "urn:hidaaas:policy:at_card"
}

The authentication type is bound to the:

Channel - CH_EXTRAPP
User type - UT_EMP

The application definition is created with the following values:

Device Type:
- id - identifier generated by the back end in the format <card application ID>_DT_CARD (for example, APP_CARD_DT_CARD)
Authentication Policy:
- id - identifier generated by the back end in the format <card application ID>_AT_CARD (for example, APP_CARD_AT_CARD)
- validCredentialPolicies is also updated with the generated credential types based on the defined typelist
Credential Type:

For every typelisted, a credentialtype is created (if not already present) in the format CT_CARD_<type>.

Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:application:CardAuth"],
    "id": "APP_CARD",
    "meta": {
        "resourceType": "Card Auth Application",
        "location": "https://[base-server-url]/scim/tenant/v2/Application/CardAuth/APP_CARD",
        "version": "1"
    },
    "name": "MiFare cards application",
    "notes": "Application for MiFare 1K Contactless Writable cards",
    "type": [ "MIFARE Classic", "Seos" ],
    "deviceType": {
        "devicetypeId": "APP_CARD_DT_CARD",
        "name": "Contactless Card Device",
        "notes": "Generic device for contactless cards",
        "maximumDevicePerUser": 5
    },
    "authenticatorPolicy": {
        "authenticatorPolicyId": "APP_CARD_AT_CARD",
        "disableThreshold": 5,
        "defaultExpiryThreshold": -1,
        "sessionTimeout": 3600000,
        "sessionValidPeriod": 86400000,
        "disabledTimeReset": 0,
        "levelOfAssurance": "urn:hidaaas:policy:at_card"
    }
}

Delete a CardAuth Application

DELETE /Application/CardAuth/{uid}

Where {uid} is the adapter id.

Copy

Sample Request URI

DELETE /configuration/{tenant}/v2/Application/CardAuth/APP_CARD

Copy

Sample Response

HTTP 204 No Content

This will delete the application's authentication policy and device type.

If the authentication is still in use (by user authenticators that have already been enrolled), the policy's validCredentialPolicies parameter is set to empty (so the authenticators can no longer be used).

The credential types are not modified or deleted.