Authenticator REST API

The Authenticator endpoint allows creating and managing authenticators which bind a user to an authenticator policy.

You can also perform specific actions such as getting challenges and registering a user for Out-of-band (OOB) authentication.

Note: The API version supported by HID Authentication Service is 10.3.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

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	/scim/{tenant}/v2/Authenticator	Retrieve all authenticators
GET	Read	/scim/{tenant}/v2/Authenticator/{id}.(String)	Retrieve authenticators for a known user
POST	Create	/scim/{tenant}/v2/Authenticator	Create new user authenticator
POST	Search	/scim/{tenant}/v2/Authenticator/.search	Search for user authenticators
POST	Action	/scim/{tenant}/v2/Authenticator/{id}.(String)	Perform a named action on the entity Get Challenge by User Code Get Challenge by Device Reset Authentication Fail Counter Deliver Challenge Register OOB Unregister OOB
PUT	Replace	/scim/{tenant}/v2/Authenticator/{id}.(String)	Fully replace a known user authenticator
DELETE	Delete	/scim/{tenant}/v2/Authenticator/{id}.(String)	Delete a known users authenticator

Required Permissions

Function	Required Permissions
GET	Read user details Read reference data Search Users
CREATE	Create authenticator Read reference data
REPLACE	Read user details Read reference data Search Users If change password: Static password – Change password user not present If update status: Static password – Update login authenticator status Device – Update device authenticator status
DELETE	Read reference data Read user details Depending on authenticator type: Static password – Delete login authenticator Device – Delete device authenticator
ACTION: USER-CHALLENGE	Read user details
ACTION: DEVICE-CHALLENGE	Read user details
ACTION: RESET	Read reference data Reset authenticators statistics
ACTION: DELIVER-CHALLENGE	Authentication Proxy
ACTION: UNREGISTER-OOB	Read user details Delete device authenticator

Get an Authenticator

[GET] /Authenticator/{id}

Where {id} is <User ID>.<Authentication Policy>

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/Authenticator/10033.AT_EMPOTP

Where 10033 is the user ID, and AT_EMPOTP is the authentication policy.

See Searching with the SCIM API to find a user by username (or other parameters) to get the user ID.

Copy

Sample Response

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator"
    ],
    "id": "10033.AT_EMPOTP",
    "externalId": "jsmith",
    "meta": {
        "resourceType": "Authenticator",
        "created": "2022-11-20T18:15:21+00:00",
        "location": "https://[base-server-url]/SCIM/tenant/v2/Authenticator/10033.AT_EMPOTP",
        "version": 1
    },
    "status": {
        "status": "ENABLED",
        "active": true,
        "startDate": "2022-11-20T18:15:21+00:00",
        "expiryDate": "2024-11-19T18:15:21+00:00"
    },
    "owner": {
        "type": "User",
        "display": "jsmith",
        "value": 10033,
        "location": "https://[base-server-url]/SCIM/tenant/v2/Users/10033"
    },
    "statistics": {
        "consecutiveFailed": 0,
        "consecutiveSuccess": 6,
        "maximumNumberOfUsages": 6,
        "totalFailed": 0,
        "totalSuccess": 6
    },
    "policy": {
        "display": "AT_EMPOTP",
        "value": "AT_EMPOTP",
        "location": "https://[base-server-url]/SCIM/tenant/v2/Policy/Authenticator/AT_EMPOTP"
    },
    "lastSuccessfulDevice": {
        "type": "Device",
        "value": "127474",
        "$ref": "https://[base-server-url]/SCIM/tenant/v2/Device/127474"
    }
}

Create an Authenticator

[POST] /Authenticator

Accept: application/scim+json

Expected attributes:

owner.value – the ID of the user for which the authenticator is created
owner:display – ID reference for LDAP users not yet bound in HID Authentication Service when creating an authenticator with LDAP passthrough
policy.value – the authenticator policy ID
status.status – status of the authenticator (ENABLED or DISABLED)
status.startDate – authenticator ‘valid from’ date
status.expiryDate – authenticator ‘valid to’ date

Create Device Authenticator

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Authenticator

Copy

Sample Request

{
    "schemas": [ "urn:hid:scim:api:idp:2.0:Authenticator" ],
    "status": {
        "status": "ENABLED",
        "startDate": "2020-09-11T16:45:46+00:00",
        "expiryDate": "2025-09-11T16:45:46+00:00"
    },
    "owner": { "value": "11288"},
    "policy": { "value": "AT_CUSTOTP"}
}

Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Authenticator"],
    "id": "11288.AT_CUSTOTP",
    "externalId": "jdoe",
    "meta": {
        "resourceType": "Authenticator",
        "created": "2020-09-11T16:45:46+00:00",
        "location": "https://[base-server-url]/scim/tenant/v2/Authenticator/11288.AT_CUSTOTP",
        "version": "1"
    },
    "status": {
        "status": "ENABLED",
        "active": false,
        "startDate": "2020-09-11T16:45:46+00:00",
        "expiryDate": "2025-09-11T16:45:46+00:00"
    },
    "owner": {
        "type": "User",
        "display": "jdoe",
        "value": "11288",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Users/11288"
    },
    "statistics": {
        "consecutiveFailed": "0",
        "consecutiveSuccess": "0",
        "maximumNumberOfUsages": "0",
        "totalFailed": "0",
        "totalSuccess": "0"
    },
    "policy": {
        "display": "AT_CUSTOTP",
        "value": "AT_CUSTOTP",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_CUSTOTP"
    }
}

Create Password Authenticator

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Authenticator

Copy

Sample Request

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Authenticator"],
    "policy": {"value": "AT_CUSTPW"},
    "status": {
        "status": "ENABLED",
        "startDate": "2015-05-15T18:15:21+00:00"
        "expiryDate": "2018-05-15T18:15:21+00:00",
    },
    "owner": {"value": "12345"},
    "urn:hid:scim:api:idp:2.0:Password": {
        "username" : "user12345",
        "password" : "Zaqaawsx12"
    }
}

Copy

Sample Response

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator",
        "urn:hid:scim:api:idp:2.0:Password"
    ],
    "id": "12345.AT_CUSTPW",
    "externalId": "user12345",
    "meta": {
        "resourceType": "Authenticator",
        "created": "2015-05-15T18:15:21Z",
        "location": "https://[base-server-url]/SCIM/tenant/v2/Authenticator/12345.AT_CUSTPW",
        "version": "1"
    },
    "status": {
        "status": "ENABLED",
        "active": true,
        "expiryDate": "2018-05-15T18:15:21Z",
        "startDate": "2015-05-15T18:15:21Z"
    },
    "owner": {
        "type": "User",
        "display": "user12345",
        "value": "12345",
        "$ref": "https://[base-server-url]/SCIM/tenant/v2/Users/12345"
    },
    "statistics": {
        "consecutiveFailed": "0",
        "consecutiveSuccess": "0",
        "maximumNumberOfUsages": "0",
        "totalFailed": "0",
        "totalSuccess": "0"
    },
    "policy": {
        "display": "AT_CUSTPW",
        "value": "AT_CUSTPW",
        "$ref": "https://[base-server-url]/SCIM/tenant/v2/Policy/Authenticator/AT_CUSTPW"
    },
    "urn:hid:scim:api:idp:2.0:Password": {
        "username": "user12345"
    }
}

Create LDAP Passthrough Authenticator

To create an authenticator for an LDAP user who is not yet bound in HID Authentication Service, you can use the owner.display property with the username.

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Authenticator

Copy

Sample Request

{
    "policy": {"value":"AT_LDAP"},
    "status": {
        "status": "ENABLED",
        "expiryDate": "2020-05-15T18:15:21+00:00",
        "startDate": "2019-05-15T18:15:21+00:00"
    },
    "owner":{
        "display":"LDAP_USER_009"
    }
}

Copy

Sample Response

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator"
    ],
    "id": "11324.AT_LDAP",
    "externalId": "LDAP_USER_009",
    "meta": {
        "resourceType": "Authenticator",
        "created": "2019-05-15T18:15:21Z",
        "location": "https://[base-server-url]/scim/tenant/v2/Authenticator/11324.AT_LDAP",
        "version": "1"
    },
    "status": {
        "status": "ENABLED",
        "active": true,
        "expiryDate": "2020-05-15T18:15:21Z",
        "startDate": "2019-05-15T18:15:21Z"
    },
    "owner": {
        "type": "User",
        "display": "LDAP_USER_009",
        "value": "11324",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Users/11324"
    },
    "statistics": {
        "consecutiveFailed": "0",
        "consecutiveSuccess": "0",
        "maximumNumberOfUsages": "0",
        "totalFailed": "0",
        "totalSuccess": "0"
    },
    "policy": {
        "display": "AT_LDAP",
        "value": "AT_LDAP",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_LDAP"
    }
}

Note: The value for owner.value is present in the response because the LDAP user is automatically bound internally in HID Authentication Service when creating an LDAP passthrough authenticator.

Replace an Authenticator

[PUT] /Authenticator/{id}

Where {id} is <User ID>.<Authentication Policy>

Accept: application/scim+json

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.

Updatable attributes:

status.status ENABLED or DISABLED

Passwords can also be modified:

urn:hid:scim:api:idp:2.0:Password

Copy

Sample Request URI

[PUT] /scim/{tenant}/v2/Authenticator/10275.AT_EMPPWD

Copy

Sample Request to update a password

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator",
        "urn:hid:scim:api:idp:2.0:Password"
    ],
    "urn:hid:scim:api:idp:2.0:Password": {
        "username": "user12345",
        "password": "apqm2687"
    } 
}

Copy

Sample Response

{
     "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator",
        "urn:hid:scim:api:idp:2.0:Password"
    ],
    "id": "10275.AT_EMPPWD",
    "externalId": "jdoe",
    "meta": {
        "resourceType": "Authenticator",
        "created": "2023-05-15T18:15:21+00:00",
        "location": "https://[base-server-url]/scim/tenant/v2/Authenticator/10275.AT_EMPPWD",
        "version": 1
    },
    "status": {
        "status": "ENABLED",
        "active": true,
        "startDate": "2023-05-15T18:15:21+00:00",
        "expiryDate": "2023-11-15T18:15:21+00:00"
    },
    "owner": {
        "type": "User",
        "display": "user12345",
        "value": 12345,
        "location": "https://[base-server-url]/scim/tenant/v2/Users/12345"
    },
    "statistics": {
        "consecutiveFailed": 0,
        "consecutiveSuccess": 0,
        "maximumNumberOfUsages": 0,
        "totalFailed": 0,
        "totalSuccess": 0
    },
    "policy": {
        "display": "AT_EMPPWD",
        "value": "AT_EMPPWD",
        "location": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_EMPPWD"
    },
    "urn:hid:scim:api:idp:2.0:Password": {
        "username": "user12345"
    }
}

Search for an Authenticator

Supported search criteria are:

SCIM Attribute	Operators supported
owner.value	eq
id	eq

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Authenticator/.search

Copy

Sample Request

[POST] /scim/{tenant}/v2/Authenticator/.search
{
    "filter": "owner.value eq 20792",
}

Where the filter attribute can be used to reduce the number of records you want to see.

You can use the and operator within the filters.

Note: For further information, see Searching with the SCIM API.

Delete an Authenticator

All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:

Copy

Delete entity

DELETE https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/{id}

Accept: application/scim+json

Copy

Sample Response

HTTP/1.1 204 No content

Actions on an Authenticator

Get Challenge by User Code

[POST] /Authenticator/{id}

Where {id} is <User ID>.<Authentication Policy>

Accept: application/scim+json

The following attributes can be used to identify the device to use:

USER.EXTERNALID – user external id
CHANNEL – if a specific Channel is required to make the call

Note: If the USER.EXTERNALID attribute is used (recommended), user id is not used and can be omitted.

Copy

Sample Request URI

[POST] /Authenticator/.AT_EMPOTP

Copy

Sample Request

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "USER-CHALLENGE",
        "attributes": [
            {
                "name": "CHANNEL",
                "value": "CH_IIS"
            },
            {
                "name": "USER.EXTERNALID",
                "value": "myUser"
            }
        ]
    }
}

Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "attributes": [
        {
            "name": "CHALLENGE",
            "type": "string",
            "value": "32132427",
            "readOnly": false
        },
        {
            "name": "CHALLENGE.ID",
            "type": "string",
            "value": "0",
            "readOnly": false
        },
        {
            "name": "REQUEST.STATUS",
            "type": "string",
            "value": "1",
            "readOnly": false
        },
        {
            "name": "REQUEST.REASON",
            "type": "string",
            "value": "-1",
            "readOnly": false
        },
        {
            "name": "REQUEST.ERROR_MESSAGE",
            "type": "string",
            "readOnly": false
        }
    ]
}

Get Challenge by Device

[POST] /Authenticator/{id}

Where {id} is <User ID>.<Authentication Policy>

Accept: application/scim+json

Following attributes can be used to identify the device to use:

DEVICETYPE – device type code
DEVICE.EXTERNALID – device's serial number
DEVICE.ID – device ID
CHANNEL – if a specific Channel is required to make the call

Copy

Sample Request URI

[POST] /Authenticator/12345.AT_EMPOTP

Copy

Sample Request

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "DEVICE-CHALLENGE",
        "attributes": [
            {
                "name": "DEVICE.EXTERNALID",
                "value": "14851787148870370719"
            },
            {
                "name": "CHANNEL",
                "value": "CH_IIS"
            }
        ]
    }
}

Copy

Sample Response

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "attributes": [
        {
            "name": "CHALLENGE",
            "type": "string",
            "value": "45551649",
            "readOnly": false
        },
        {
            "name": "CHALLENGE.ID",
            "type": "string",
            "value": "0",
            "readOnly": false
        },
        {
            "name": "REQUEST.STATUS",
            "type": "string",
            "value": "1",
            "readOnly": false
        },
        {
            "name": "REQUEST.REASON",
            "type": "string",
            "value": "-1",
            "readOnly": false
        },
        {
            "name": "REQUEST.ERROR_MESSAGE",
            "type": "string",
            "readOnly": false
        }
    ]
}

Reset Authentication Fail Counter

After multiple failed authentication attempts, the authenticator becomes disabled. You can reset the failure counter to enable it.

[POST] /Authenticator/{id}

Where {id} is <User ID>.<Authentication Policy>

Accept: application/scim+json

Copy

Sample Request URI

[POST] /Authenticator/12345.AT_TDS

Copy

Sample Request

{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "RESET"
    }
}

Copy

Sample Response

HTTP 200 OK

Deliver Challenge

[POST] /Authenticator/{id}

Where {id} is <User ID>.<Authentication Policy>, user ID is not used and can be omitted.

Accept: application/scim+json

The following attributes can be used to identify the device to use:

DEVICETYPE – device type code
DEVICE.EXTERNALID – device's serial number
DEVICE.ID – device ID
CHANNEL – if a specific Channel is required to make the call
USER.EXTERNALID – user external ID

Copy

Sample Request URI

[POST] /Authenticator/.AT_TDS

Copy

Sample Request

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator",
        "urn:hid:scim:api:idp:2.0:Action"
    ],
    "id": "11914.AT_TDS",
    "urn:hid:scim:api:idp:2.0:Action": {
        "schemas": [
            "urn:hid:scim:api:idp:2.0:Action"
        ],
        "attributes": [
            {
                "name": "tds",
                "value": "{amount, 400.00},{sortcode,20-30-90}, {account_to,1234-5678}"
            },
            {
                "name": "id",
                "value": "tenant.CH_TDS.AT_TDS.11936"
            },
            {
                "name": "correlationid",
                "value": "some_correlation_id"
            },
            {
                "name": "DEVICE.ID",
                "value": "11936"
            }
        ],
        "action": "DELIVER-CHALLENGE"
    }
}

Important: To send a CIBA notification for push-based authentication request, the correlationid must be in the <client_notification_token>:<auth_req_id> format, where:

client_notification_token is a bearer token for the CIBA callback
auth_req_id is a unique identifier of the authentication request (for example, you can generate a random GUID)

Copy

Sample correlationid for CIBA callback

{
    "name": "correlationid",
    "type": "string",
    "value": "c8330849-a9a2-4cad-8d75-8ae4ec180a72:dc3f84d8-6042-4696-b511-89ad330484df"
}

Copy

The CIBA Callback URL is then called with:

Header:
Authorization: Bearer c8330849-a9a2-4cad-8d75-8ae4ec180a72
Body:
{
    ...
    "auth_req_id": "dc3f84d8-6042-4696-b511-89ad330484df",
    ...
}

If you do not need the client_notification_token, the correlationid can contain only the :<auth_req_id>.

Copy

Sample Response

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Action"
    ],
    "attributes": [
        {
            "name": "CHALLENGE",
            "type": "string",
            "value": "eyJhbGciOiJkaXIiLCJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0=..r7-tFXSCyn9Md3_VZ3kdNg==.5tSRV-kqQ7JUuTS3HJtaY0sM2eFKYAS11zZK5vMxrgcmcCBU79-zX6IeQs7JQYP9t1Wv9iYGuD_hXR_Q5x_mgBRBHoWWaX-4jsr7dMcMatw=.WFfg3MQaHPyZqt7nUX5ZzEFxeovCkUJGVFYc-RWjsYU=",
            "readOnly": false
        },
        {
            "name": "CHALLENGE.ID",
            "type": "string",
            "value": "11962",
            "readOnly": false
        },
        {
            "name": "REQUEST.STATUS",
            "type": "string",
            "value": "1",
            "readOnly": false
        },
        {
            "name": "REQUEST.REASON",
            "type": "string",
            "value": "-1",
            "readOnly": false
        },
        {
            "name": "REQUEST.ERROR_MESSAGE",
            "type": "string",
            "readOnly": false
        }
    ]
}

Register OOB

[POST] /Authenticator/

Accept: application/scim+json

The following attributes are mandatory:

owner – display (user external id) or value (user id) can be used
policy - code of the authentication type
urn:hid:scim:api:idp:2.0:Action :
- action - REGISTER-OOB (static value)
- attributes:
  - name - OOB_DEVICETYPE_CODE (static value)
  - value - code of device type that is compatible with credential type bound to the authentication type
    
    For example, DT_OOBEML with AT_OOBEML or DT_OOBSMS with AT_OOBSMS.

The following attribute is optional:

activationCode – if not set in the request, the server will generate one

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Authenticator

Copy

Sample Request

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator"
    ],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "REGISTER-OOB",
        "attributes": [
            {
                "name": "OOB_DEVICETYPE_CODE",
                "value": "DT_OOBEML"
            }
        ]
    },
    "activationCode": "1234",
    "owner": {
        "value": "17606",
        "display": "user1"
    },
    "policy": {
        "value": "AT_OOBEML"
    }
}

Copy

Sample Response

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Authenticator"
    ],
    "id": "17606.AT_OOBEML",
    "externalId": "user1",
    "meta": {
        "resourceType": "Authenticator",
        "created": "2020-05-21T08:19:47Z",
        "location": " https://[base-server-url]/scim/tenant/v2/Authenticator/17606.AT_OOBEML",
        "version": "1"
    },
    "status": {
        "status": "ENABLED",
        "active": true,
        "expiryDate": "2025-05-20T08:19:47Z",
        "startDate": "2020-05-21T08:19:47Z"
    },
    "owner": {
        "type": "User",
        "display": "user1",
        "value": "17606",
        "$ref": " https://[base-server-url]/scim/tenant/v2/Users/117606"
    },
    "statistics": {
        "consecutiveFailed": "0",
        "consecutiveSuccess": "0",
        "maximumNumberOfUsages": "0",
        "totalFailed": "0",
        "totalSuccess": "0"
    },
    "policy": {
        "display": "AT_OOBEML",
        "value": "AT_OOBEML",
        "$ref": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_OOBEML"
    },
    "activationCode": "1234"
}

Unregister OOB

[POST] /Authenticator/{id}

Where {id} is <User ID>.<Authentication Policy>

Accept: application/scim+json

Note:

The USER.EXTERNALID attribute is optional (userExternald will be discovered from the <UserID> in the URL).
If the USER.EXTERNALID attribute is used, the <UserId> in the URL is optional.

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Authenticator/17606.AT_OOBEML

Copy

Sample Request

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Action"
    ],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "UNREGISTER-OOB",
        "attributes": [
            {
                "name": "USER.EXTERNALID",
                "value": "user1"
            }
        ]
    }
}

Copy

Sample Response

HTTP 200 OK