Applications (PINAuth) REST API

The Application/PINAuth endpoint allows creating and managing all the definitions (user type, channel and authentication policy) required for PIN 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

Entity Action	Request URI	Description
Read	/configuration/{tenant}/v2/Application/PINAuth	Retrieve the list of all PINAuth Applications
Read	/configuration/{tenant}/v2/ Application/PINAuth /{uid}	Retrieve a PINAuth Application
Create	/configuration/{tenant}/v2/ Application/PINAuth	Create a PINAuth Application
Delete	/configuration/{tenant}/v2/ Application/PINAuth /{uid}	Delete a PINAuth Application

Get All PINAuth Applications

GET /Application/PINAuth

Copy

Sample Request URI

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

Copy

Sample Request

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

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:PINAuth"],
            "id": "PIN_FOR_USERS",
            "meta": {
                "resourceType": "PIN Auth Application",
                "location": "https://[base-server-url]/scim/tenant/v2/Application/PINAuth/PIN_FOR_USERS",
                "version": "1"
            },
            "name": "PIN authentication application",
            "notes": "Application for PIN authentication",
            "constraints": {
                "minLength": 4,
                "maxLength": 12,
                "characterRange" : "numOrAlpha"
            },
            "usageRestrictions": {
                "userType": "UT_EMP",
                "validChannelCodes": [ "CH_EXTRAPP" ]
            },
            "sessionPolicy": {
                "disableThreshold": 5,
                "defaultExpiryThreshold": -1,
                "sessionValidPeriod": 86400000,
                "disabledTimeReset": 0,
                "levelOfAssurance": "urn:hidaaas:policy:at_pin"
            }
        }
    ]
}

Get a PINAuth Application

GET /Application/PINAuth/{uid}

where {uid} is the application id.

Copy

Sample Request

GET /configuration/{tenant}/v2/Application/PINAuth/PIN_FOR_USERS

Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:application:PINAuth"],
    "id": "PIN_FOR_USERS",
    "meta": {
        "resourceType": "PIN Auth Application",
        "location": "https://[base-server-url]/scim/tenant/v2/Application/PINAuth/PIN_FOR_USERS",
        "version": "1"
    },
    "name": "PIN authentication application",
    "notes": "Application for PIN authentication",
    "constraints": {
        "minLength": 4,
        "maxLength": 12,
        "characterRange" : "numOrAlpha"
    },
    "usageRestrictions": {
        "userType": "UT_EMP",
        "validChannelCodes": [ "CH_EXTRAPP" ]
    },
    "sessionPolicy": {
        "disableThreshold": 5,
        "defaultExpiryThreshold": -1,
        "sessionValidPeriod": 86400000,
        "disabledTimeReset": 0,
        "levelOfAssurance": "urn:hidaaas:policy:at_pin"
    }
}

Create a PINAuth Application

POST /Application/PINAuth

Copy

Sample Request URI

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

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 ID for the application's authentication policy If it already exists, it is re-used. Otherwise, the new policy is created and bound to the default channel (CH_EXTRAPP)
constraints	minLength - minimum length of the PIN (default is 4) maxLength - maximum length of the PIN (default is 12) characterRange - allowed format of the PIN Possible values are: numOrAlpha (default) Num Alpha
usageRestrictions	userType - the user type allowed for this application (default is UT_EMP) validChannelCodes - the channels allowed for this application (default is CH_EXTRAPP)
sessionPolicy	The customizable authentication policy parameters: id - (optional) code for authentication policy to create (default value is AT_PIN) If the parameter is not present, the id of the application is used. 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) sessionValidPeriod - (optional) session validity (default value is 86400000 milliseconds) disabledTimeReset - (optional) auto unblock of the authenticator (default value is 0) AllowExpiredReset - (optional) number of allowed reset requests for an expired PIN authenticator (default is 3) levelOfAssurance - (optional) level of authenticator / ACR value (default value is urn:hidaaas:policy:<at_id> where <at_id> is the authenticator policy ID in lowercase)

Copy

Sample Request

{
    "id": "PIN_FOR_USERS",
    "name": "PIN authentication application",
    "notes": "Application for PIN authentication",
    "constraints": {
        "minLength": 4,
        "maxLength": 12,
        "characterRange" : "numOrAlpha"
    },
    "usageRestrictions": {
        "userType": "UT_EMP",
        "validChannelCodes": [ "CH_EXTRAPP" ]
    },
    "sessionPolicy": {
        "disableThreshold": 5,
        "defaultExpiryThreshold": -1,
        "sessionValidPeriod": 86400000,
        "disabledTimeReset": 0,
        "levelOfAssurance": "urn:hidaaas:policy:at_pin"
    }
}

The authentication type is bound to the:

Channel - CH_EXTRAPP
User type - UT_EMP

The application definition is created with the following values:

Authentication Policy:
- id - identifier generated by the back end in the format <PIN application ID> (for example, PIN_FOR_USERS) or the value defined in the sessionPolicy parameters (for example, AT_PIN)
- constraints, usageRestrictions and sessionPolicy parameters are also updated with the specified values

Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:application:PINAuth"],
    "id": "PIN_FOR_USERS",
    "meta": {
        "resourceType": "PIN Auth Application",
        "location": "https://[base-server-url]/scim/tenant/v2/Application/PINAuth/PIN_FOR_USERS",
        "version": "1"
    },
    "name": "PIN authentication application",
    "notes": "Application for PIN authentication",
    "constraints": {
        "minLength": 4,
        "maxLength": 12,
        "characterRange" : "numOrAlpha"
    },
    "usageRestrictions": {
        "userType": "UT_EMP",
        "validChannelCodes": [ "CH_EXTRAPP" ]
    },
    "sessionPolicy": {
        "disableThreshold": 5,
        "defaultExpiryThreshold": -1,
        "sessionValidPeriod": 86400000,
        "disabledTimeReset": 0,
        "levelOfAssurance": "urn:hidaaas:policy:at_pin"
    }
}

Delete a PINAuth Application

DELETE /Application/PINAuth/{uid}

Where {uid} is the adapter id.

Copy

Sample Request URI

DELETE /configuration/{tenant}/v2/Application/PINAuth/PIN_FOR_USERS

Copy

Sample Response

HTTP 204 No Content

This will also delete the application's authentication policy.

If the authentication is still in use (by user authenticators that have already been enrolled), the deletion fails and an error is returned.