MFA / API Documentation
The majority of the below code can be reviewed in InstallPath\SelfServiceSite\assets\self-service-portal-****randomguid***.js if clarification is needed.
Return of user enrolled methods GET
The path: https://servername.fqdn.etc/api/v1/users/, followed by the username/domain (https://servername.fqdn.etc/api/v1/users/epsilon/2faone) could return JSON data similar to what is shown below:
{
"data":{
"type":"user",
"userId":6,
"username":"epsilon",
"domain":"2FAONE",
"authMethods"{
{
"type":"authMethod",
"authMethodId":2,
"displayName":"AD",
"pinRequired":false,
"pinLabel":""},
{
"type":"authMethod",
"authMethodId":10,
"displayName":"OTP",
"pinRequired":false,
"pinLabel":"PIN"},
{
"type":"authMethod",
"authMethodId":11,
"displayName":"PingMe",
"pinRequired":false,
"pinLabel":""
}
]
}
} UserID being their UserID in our database. AuthMethods returned are only the available enrolled auth methods, any non enrolled methods are omitted.
Curl Example for user 2faone\conroe
curl -X GET \
https://dev.cloud.2fa.com/api/v1/users/conroe/2faone \
-H 'Postman-Token: 131472dc-7e45-4a21-9a7d-f73354d33bfe' \
-H 'cache-control: no-cache'Response --- 200 OK
{
"data": {
"type": "user",
"userId": 80,
"username": "conroe",
"domain": "2FAONE",
"authMethods": [
{
"type": "authMethod",
"authMethodId": 2,
"authProfileId": 0,
"displayName": "AD",
"pinRequired": false,
"pinLabel": ""
},
{
"type": "authMethod",
"authMethodId": 10,
"authProfileId": 13,
"displayName": "OTP",
"pinRequired": true,
"pinLabel": "PIN"
},
{
"type": "authMethod",
"authMethodId": 11,
"authProfileId": 0,
"displayName": "PingMe",
"pinRequired": false,
"pinLabel": ""
},
{
"type": "authMethod",
"authMethodId": 15,
"authProfileId": 12,
"displayName": "FIDO",
"pinRequired": true,
"pinLabel": "PIN"
}
]
}
}Note
NOTE: The information for all active users in the database will be returned. The default authentication set and a userID outside of the range of existing IDs will be returned for any nonexistent users.
Authenticate a User to Generate an AuthToken
https://servername/api/v1/authenticate/<methodID>
Currently Supported Method IDs:
1 RapidIdentity Password
2 AD
6 Contactless Card
10 OTP
11 PingMe
15 FIDO
Body
{
"userId": “<the user id received from the api/v1/user call>",
"methodId": “<the method id as listed above>",
"firstData": “<whatever is the default auth data required, e.g. card number, bio template, etc. - for PingMe it can just be an empty string or put in the words “PingMe">",
"secondData": “<whatever is the second factor required, if required, e.g. PIN - for PingMe it can just be an empty string or put in the words “PingMe”>"
}
Response 200 OK
{
"data": {
"type": "authToken",
"authToken": "<example string21176a8a-9738-4997-ad75-68c3a6a59772>",
"userId": 80
}
}Curl Examples
Example for Password
curl -X POST \
https://dev.cloud.2fa.com/api/v1/authenticate \
-H 'Content-Type: application/json' \
-H 'Postman-Token: ca71d64e-0739-4ba5-8ead-0cc30005c8b9' \
-H 'cache-control: no-cache' \
-d '{"userId":"80",
"methodId": "2",
"firstData":"<string>",
"secondData":"" }'Example Authenticate Card
curl -X POST \
https://dev.cloud.2fa.com/api/v1/authenticate \
-H 'Content-Type: application/json' \
-H 'Postman-Token: fb50f1db-3ad7-4188-ad40-43783568db6e' \
-H 'cache-control: no-cache' \
-d '{"userId":"80",
"methodId": "6",
"firstData":"049D651AB95380",
"secondData":"124578" }'Method ID 6 = contactless
firstData = CUID of card submitted as read by Active X plugin
secondData = user pin submitted if required. Leave blank if no PIN required
Example Authenticate PING
curl -X POST \
https://dev.cloud.2fa.com/api/v1/authenticate \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 0a802514-f7b7-42d9-8d7f-3ff35f7b1ae8' \
-H 'cache-control: no-cache' \
-d '{"userId":"80",
"methodId": "11",
"firstData":"PingMe",
"secondData":"" }'firstData will be static PingMe
SecondData = is user PIN.
If no PIN is submitted, ping will automatically send. If PIN is submitted incorrectly, no PING will be sent and 403 will return.
Example for OTP
curl -X POST \
https://dev.cloud.2fa.com/api/v1/authenticate \
-H 'Content-Type: application/json' \
-H 'Postman-Token: c1c5cf29-cb58-4f65-a0e1-0d6b41982c83' \
-H 'cache-control: no-cache' \
-d '{"userId":"80",
"methodId": "10",
"firstData":"4312765",
"secondData":"" }'firstData is users OTP or a valid auth tokenSecond data is user PIN -- not required for AuthCode
Ex Authenticate RapidIdentity password
curl -X POST \
https://dev.cloud.2fa.com/api/v1/authenticate \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 0fbb8de1-76be-4352-9f7c-3f8b4e8a089f' \
-H 'cache-control: no-cache' \
-d '{"userId":"1",
"methodId": "1",
"firstData":"<string>",
"secondData":"" }'GET Credential
When authenticated with AuthToken, should return users enrolled credentials with device IDs. This can be used to display all enrolled devices for a user. Headers must include a valid userID and AuthToken combination.
curl -X GET \ https://dev.cloud.2fa.com/api/v1/credentials \ -H 'Content-Type: application/json' \ -H 'Postman-Token: 1ea78200-3ecc-480d-8070-90da1ded2ba9' \ -H 'authToken: 0b05c0b2-0372-4c7c-a787-6a5c2f987fb5' \ -H 'cache-control: no-cache' \ -H 'userID: 80'
Response 200 OK
Example for Response
[
{
"type": "credential",
"authMethodId": 2,
"deviceId": 80,
"displayName": "2FAONE\\conroe",
"credentialData": ""
},
{
"type": "credential",
"authMethodId": 10,
"deviceId": 10039,
"displayName": "5568ef96b1a81528",
"credentialData": "Soft Token"
},
{
"type": "credential",
"authMethodId": 10,
"deviceId": 61603,
"displayName": "1113",
"credentialData": "Hard Token"
},
{
"type": "credential",
"authMethodId": 15,
"deviceId": 80186,
"displayName": "Gorp",
"credentialData": ""
}
]Deleting User Credentials
HTTPDELETE
servername/api/v1/credentials/<methodID>/<deviceID>
Valid userID and AuthToken must be submitted in headers
Method ID and Device ID can be retrieved from /credentials GET
BODY should be empty
Response 200 OK
{
"data": [
{
"type": "credential",
"authMethodId": <methodID>, "deviceId": <deviceID>,
"displayName": "<string>",
"credentialData": "Soft Token"
}
]
}
Above data is returned if additional deviceIDs of same method exist
OR If no other devices of same method ID exist
{
"data": []
}
curl -X DELETE \
https://dev.cloud.2fa.com/api/v1/credentials/10/61603 \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 1d0eb191-39e5-40f1-b375-ddd88e33bcdd' \
-H 'authToken: 4b607dc7-4f7f-4216-976d-76b107209d13' \
-H 'cache-control: no-cache' \
-H 'userID: 80' \
-d ' 'Manually nullify Auth Token -- POST
Post to api/v1/authenticate/logout with userId and authToken to kill in header
Auth token expiration apllies otherwise from Database Settings table
dbo.Settings
AuthTokenAbsoluteExpirationTime = time in seconds until authtoken is invalidated regardless of inactivity
AuthTokenExpirationTime = time in seconds until authtoken is invalidated due to inactivity
Enroll a credential -- POST
api/v1/credentials/methodID
Example for Contactless
api/v1/credentials/6
{
"userId": 80,
"methodId": 6,
"credData": {
"cuid": "049d651ab95380AAAA",
"pin" : "1245",
"label": "HereisFre"}
}Cuid = cuid of card as read by Active X Plugin
Pin = user PIN to be submitted
Note
If omitted and UseGlobalPIN = true in Settings table, pin set in user’s OTP data will be automatically submitted as the PIN.
Label = Users choice for card name, may be left blank
GET /api/v1/credentials/6 HTTP/1.1
Host: dev.cloud.2fa.com
authToken: 21176a8a-9738-4997-ad75-68c3a6a59772
userID: 80
Content-Type: application/json
cache-control: no-cache
Postman-Token: 0d7ed2e7-aea0-4eba-8d44-2732d9448291
{
"userId": 80,
"methodId": 6,
"credData": {
"cuid": "049d651ab95380AAAA",
"pin" : "1245",
"label": "HereisFre"}
}------WebKitFormBoundary7MA4YWxkTrZu0gW--Enroll OTP
{
"userId": “80”,
"methodId": "10",
"credData": {
"serial": “<serialnumberOfOTP”,
"otp1": “111222”,
"otp2": “222333”,
"pin": “1245”
}curl -CX POST\
https://dev.cloud.2fa.com/api/v1/credentials/10 \
-H 'Content-Type: application/json' \
-H 'Postman-Token: d7ada9ac-7f0c-4109-a94c-fa7b797dd32d' \
-H 'authToken: ae6494a4-3899-4293-a130-4a00cf3fd259' \
-H 'cache-control: no-cache' \
-H 'userID: 80' \
-d '{
"userId": “80”,
"methodId": "10",
"credData": {
"serial": “<serialnumberOfOTP”,
"otp1": “111222”,
"otp2": “222333”,
"pin": “1245”
}
'Response 200 OK
Or
Response 400 Bad Request
{
"Message": "Could not process request"
}Indicates that OTPs submitted failed to validate
Return Custom Links
Using the self-service APIs, after a user has a authenticated login, call /users/customlinks. If the user is in an admin-type role then the response will include an URL to the admin portal and a label.
Examples of admin-type roles
Manage_Authentication_Methods, Manage_Authentication_Sets, Manage_Roles, Manage_Users, Manage_Reports, Manage_Clients, or Configure_CM
Example response to /users/customlinks
{
“data”:[
{
“url”:“https://mfaqa.cloud.2fa.com/ONE/admin_portal/validateAuthToken.aspx?token=dd60e583-cadb-47f5-8182-f6fbbd599d71&id=1“,
“label”:“Admin Portal”
}
]
}submit USERID and AuthToken headers
curl -X GET \ https://dev.cloud.2fa.com/api/v1/users/customlinks \ -H 'Content-Type: application/json' \ -H 'Postman-Token: bd6f5cb7-025d-4902-aa9d-802679c0aae7' \ -H 'authToken: 01f25269-7e5e-4589-a741-39f5e932abcc' \ -H 'cache-control: no-cache' \ -H 'userID: 1'
Response 200 OK
{
"data": [
{
"url": "https://dev.cloud.2fa.com/ONE/admin_portal/validateAuthToken.aspx?token=01f25269-7e5e-4589-a741-39f5e932abcc&id=1",
"label": "Admin Portal"
}
]
}Note
Above response reads Admin Portal URL from dbo.Settings and provide link allows user to login directly to Admin portal
Response 403 Forbidden
Auth token is invalid for userID provided