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.
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.
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 |
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 |
|
CREATE |
|
REPLACE |
|
DELETE |
|
ACTION: USER-CHALLENGE |
|
ACTION: DEVICE-CHALLENGE |
|
ACTION: RESET |
|
ACTION: DELIVER-CHALLENGE |
|
ACTION: UNREGISTER-OOB |
|
Get an Authenticator
[GET] /Authenticator/{id}
Where {id} is <User ID>.<Authentication Policy>
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.
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 ActivID AS 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
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"}
}
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
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"
}
}
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 Security Question Authenticator
For details about managing security question prompts, see Configure Security Questions.
Sample Request
{
"schemas": [
"urn:hid:scim:api:idp:2.0:Authenticator"
],
"policy": {
"value": "AT_CUSTQA"
},
"status": {
"status": "ENABLED",
"startDate": "2015-05-15T18:15:21+00:00",
"expiryDate": "2018-05-15T18:15:21+00:00"
},
"owner": {
"value": "11288"
},
"urn:hid:scim:api:idp:2.0:SecurityQuestion": {
"prompts": [
{
"prompt": {
"value": "PR_SIBLING"
},
"answer": "sibling name"
},
{
"prompt": {
"value": "PR_NICK"
},
"answer": "nickname"
},
{
"prompt": {
"value": "PR_ANIMAL"
},
"answer": "animal name"
}
]
}
}
Sample Response
{
"schemas": [
"urn:hid:scim:api:idp:2.0:Authenticator",
"urn:hid:scim:api:idp:2.0:SecurityQuestion"
],
"id": "11288.AT_CUSTQA",
"externalId": "jdoe",
"meta": {
"resourceType": "Authenticator",
"created": "2015-05-15T18:15:21Z",
"location": "https://[base-server-url]/scim/tenant/v2/Authenticator/11288.AT_CUSTQA",
"version": "1"
},
"status": {
"status": "ENABLED",
"active": true,
"expiryDate": "2018-05-15T18:15:21Z",
"startDate": "2015-05-15T18:15:21Z"
},
"owner": {
"type": "User",
"display": "jdoe",
"value": "11288",
"$ref": "https://[base-server-url]/scim/tenant/v2/Users/11288"
},
"statistics": {
"consecutiveFailed": "0",
"consecutiveSuccess": "-1",
"maximumNumberOfUsages": "0",
"totalFailed": "0",
"totalSuccess": "0"
},
"policy": {
"display": "AT_CUSTQA",
"value": "AT_CUSTQA",
"$ref": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_CUSTQA"
},
"urn:hid:scim:api:idp:2.0:SecurityQuestion": {
"prompts": [
{
"prompt": {
"display": "Your oldest sibling's middle name",
"value": "PR_SIBLING"
}
},
{
"prompt": {
"display": "Childhood nickname",
"value": "PR_NICK"
}
},
{
"prompt": {
"display": "Name of your first stuffed animal?",
"value": "PR_ANIMAL"
}
}
],
"promptsRequiredForCreation": "3"
}
}
Create LDAP Passthrough Authenticator
To create an authenticator for an LDAP user who is not yet bound in ActivID AS, you can use the owner.display property with the username.
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"
}
}
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"
}
}
Replace an Authenticator
[PUT] /Authenticator/{id}
Where {id} is <User ID>.<Authentication Policy>
Accept: application/scim+json
Updatable attributes:
-
status.status ENABLED or DISABLED
Passwords
-
urn:hid:scim:api:idp:2.0:Password
-
urn:hid:scim:api:idp:2.0:SecurityQuestion
Sample Request to update Security Question answers
{
"schemas": [
"urn:hid:scim:api:idp:2.0:SecurityQuestion"
],
"urn:hid:scim:api:idp:2.0:SecurityQuestion": {
"prompts": [{
"prompt": {
"display": "In what town was your first job?",
"value": "PR_1ST_JOB"
},
"answer": "London"
}, {
"prompt": {
"display": "Enter a memorable word (greater than 8 chars)",
"value": "PR_MEMWRD"
},
"answer": "memorable word"
}, {
"prompt": {
"display": "Color of your first car",
"value": "PR_CAR_CLR"
},
"answer": "purple"
}
],
"promptsRequiredForCreation": "3"
}
}
Sample Response
{
"schemas": [
"urn:hid:scim:api:idp:2.0:Authenticator",
"urn:hid:scim:api:idp:2.0:SecurityQuestion"
],
"id": "11338.AT_EMPQA",
"externalId": "myUser",
"meta": {
"resourceType": "Authenticator",
"created": "2017-06-12T13:32:00Z",
"location": "https://[base-server-url]/scim/tenant/v2/Authenticator/11338.AT_EMPQA",
"version": "1"
},
"status": {
"status": "ENABLED",
"active": true,
"expiryDate": "2022-06-11T13:32:00Z",
"startDate": "2017-06-12T13:32:00Z"
},
"owner": {
"type": "User",
"display": "myUser",
"value": "11338",
"$ref": "https://[base-server-url]/scim/tenant/v2/Users/11338"
},
"statistics": {
"consecutiveFailed": "0",
"consecutiveSuccess": "-1",
"maximumNumberOfUsages": "0",
"totalFailed": "0",
"totalSuccess": "0"
},
"policy": {
"display": "AT_EMPQA",
"value": "AT_EMPQA",
"$ref": "https://[base-server-url]/scim/tenant/v2/Policy/Authenticator/AT_EMPQA"
},
"urn:hid:scim:api:idp:2.0:SecurityQuestion": {
"prompts": [
{
"prompt": {
"display": "In what town was your first job?",
"value": "PR_1ST_JOB"
}
},
{
"prompt": {
"display": "Enter a memorable word (greater than 8 chars)",
"value": "PR_MEMWRD"
}
},
{
"prompt": {
"display": "Color of your first car",
"value": "PR_CAR_CLR"
}
}
],
"promptsRequiredForCreation": "3"
}
}
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"
}
}
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 |
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.
Delete an Authenticator
All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:
Accept: application/scim+json
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
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"
}
]
}
}
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
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"
}
]
}
}
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
Sample Request
{
"schemas": ["urn:hid:scim:api:idp:2.0:Action"],
"urn:hid:scim:api:idp:2.0:Action": {
"action": "RESET"
}
}
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
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"
}
}
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
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"
}
}
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
- 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.
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"
}
]
}
}