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

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

MFA Guides