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.