One-factor authentication

Use this page when you want raw HTTP examples for one-factor Authentication API flows.

OTP

Get User's Authenticators

The first step is to submit a POST request to get all the authenticators that can be used to log in to the application. For example:

https://customer.region.trustedauth.com/api/web/v2/authentication/users

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the application being accessed. For example:

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111"
}

An API response is received after entering the request. For example:

{
  "availableSecondFactor": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "machineAuthenticator": null,
  "authenticationTypes": ["OTP", "TOKEN"],
  "time": 1520961989641,
  "otpDeliveryInfo": {
    "otpDefaultDelivery": "SMS",
    "availableOTPDelivery": ["SMS", "EMAIL", "VOICE"]
  }
}

The authenticator types listed in the response are those that can be used to complete an authentication challenge and log in. authenticationTypes lists all the authenticators that have been assigned to the user and can be used to complete a first-factor authentication challenge. availableSecondFactor lists the authenticators that can be used to complete a second authentication challenge after the user has completed a first-factor challenge. The authenticators listed as authenticationTypes and availableSecondFactor are defined by cross-referencing the authenticators assigned to the user with those the application’s resource rule allows to be used for authentication.

Select Authenticator

The next step is to select which authenticator to use from those listed in the previous API response. The authenticator is selected by entering a POST request. That request must be sent to the correct URL with the name of authenticator at the end. The URL is different for each authenticator that you want to select using the API call. For example:

https://customer.region.trustedauth.com/api/web/v2/authentication/users/authenticate/OTP

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the application being accessed. For example:

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111"
}

An API response is received after entering the request. For example:

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": false,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GCFi6gQPNM7eMZ3AQ7vboW8d5vL6x7vtO8tn4yAYNOpV5UYI2Xo5MZg0zYE7m/R1U1cCFm83ocC1KZ3PJbeD9zqZvPQSvxxt1KIbtD9DERd21oAVEbnqqj9/8DYUBQQoxBRfwVINlCpVt8X0ZaDMSka53ZIO9VifLwS2gjy7KNRCD9DLcDznasaYoGB2YSvj+w4bE3Z9j0bgtYmhy9swn8wmd6QMSP4eb9mH2KcqgXzCUPxTxeTZu0EkIToXD1LN8v9BCyScdCLNJ/DjOGwfmpnT4hveKX5qe/dHjgsCME5kjmHtWKlmS0SPMMMgRyNII0nCcKMZI1Khd60ubnnVoFcAUpFWG1vGJwhN6ipiuwie+EW4wAXSE1HicHhY1Q/jUQev3PvVBi+GzSKowDIorhVzApd1WP0a4686yQEMGWRdqDRltXHw7udKU8UqN5tCqUK6bZsX7x2NxabqJmmxUFBbNncuzPMPJrPNMVQtw0z8BlWCyRqYl64BZAIMTpf8F/uFPLrOHgpaV1yEiMuQBea2Hf9LyXX5Dv2L44LvABIyPZ7Jy7paeffJ7ozfLwS2VpSnjTD/1ir+p6lMYjlcfJ7l5gEoW/dS8w==",
  "otpdeliveryType": "SMS",
  "expires": 1520966778923,
  "time": 1520965879202
}

Once an authentication type is selected through the API call, Identity as a Service also provides the information necessary to complete the authentication challenge. For example, if OTP is selected, Identity as a Service generates an OTP and sends it to the user, so they can complete the authentication challenge. If kbaChallenge is selected, Identity as a Service generates the questions that must be answered to authenticate.

Complete authentication challenge

The last step is to complete the authentication process. The response for the requested authentication must be included in the last API call. For example, a POST request for OTP would be sent to:

https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/OTP/complete

The request must include the end user’s response to the authentication challenge. For example, the OTP received by the user must be included in the request to complete an OTP challenge. The URL must contain the selected authenticator (for example, OTP). An Authorization header field must be added in the header section of this request. The Authorization header stores the value received as "token" in the last request. The Authorization header can be sent with or without a type value of "Bearer". For example:

Authorization: Bearer <token>

Authorization: <token>

The body of this request should contain the Application ID and authenticator response. For example:

{
  "applicationId": "1111111-111111-111111-11111111",
  "response": "123454665"
}

An API response is received after entering the request. For example:

{
  "status": null,
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": "GNVGALEyZRj9xQnp4+cRoQ3DrMViO+wdXMyeBdG4+63V0O1+B5eBl83HVbOW7daHMf4xPzuJ/TD5j3w5zrIKE6RObuzIfyELpEWlr+JAzuXHCQocmFa1eNz2B2VshyZl3tbes9P3P6pniXZgpG0MdbEALfDm9PydJ4hcqcqDM1XsTcxSBnv+LFWV1HFKzL018Af17iJpnz8VBzOi/x5N8enkZ5g+XO/uXNCiBqDdfMkxkDzkreDXOoiGo7KPEzsuXFQLIigwnYLC2BufWaOnP2KLYGjjH7A2O+tyKsepVREKRTMDcdkcfqJsyJKm3xWl/HW1SCg2Ql2naQ6V4fK6IjrCQqZbPSQV4GL75NB1wqTf3e6ijCJwBJH9JXIov9E8Tw66sKy7dQAlODuLQ9LwhNv6BF+Ndy6HJlCDQjD0Oket4Sp8t0HDe0mTU5FnMc/ch3zuFtVHdGarjPtnt6PIZdUFn1A585q4GeY8nJwyMFu8MpRJyM81sdDe5/nEarDtPPXp3NbY+0kl4fIozogosyHzNstPcZV4rza3XQXB6047lKqs0uUeigwo2TkbKVPHxwleIxcs9d+wpQAZHhfP3IDTwa2Qq7J9PYMEfQsnz3dIFOZdNbDnusYHvp+5LppVWvky4vX5QV5ldAc2B4t+RCvtSvIABVCR+nftzLUcSm02fKU=",
  "otpdeliveryType": null,
  "expires": 1520968457173,
  "time": 1520967582294
}

Identity as a Service receives the request once it is entered and validates it.

In the example above, authenticationCompleted is marked as true because the response sent in the post request was valid.

The response from the call would indicate a failure if an invalid value is passed in the body of the response. For example:

{
  "errorCode": "invalid_user_response",
  "errorMessage": "",
  "parameters": null
}

TOKENPUSH

Get users authenticators

The first step is to submit a POST request to get all the authenticators that can be used to log in to your application. For example:

https://customer.region.trustedauth.com/api/web/v2/authentication/users

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the application being accessed. For example:

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111"
}

An API response is received after entering the response. For example:

{
  "availableSecondFactor": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "machineAuthenticator": null,
  "authenticationTypes": ["TOKENPUSH", "TOKEN", "OTP"],
  "time": 1521485688570,
  "otpDeliveryInfo": {
    "otpDefaultDelivery": "SMS",
    "availableOTPDelivery": ["SMS", "EMAIL", "VOICE"]
  }
}

TOKENPUSH is listed as one of the user's available authenticators (authenticationTypes) in the example above.

Select Authenticator

The next step is to send a POST request to use token push authentication. Send the request to a URL with TOKENPUSH at the end. For example:

https://customer.region.trustedauth.com/api/web/v2/authentication/users/authenticate/TOKENPUSH

The body of this request should contain a JSON object with User ID (containing the user id or a user alias value) and the ID of the application being accessed. The body of this request may also include transaction details, as described in Transaction details and mobile SDK push messages. For example:

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "$10,001"
    },
    {
      "detail": "Purpose",
      "value": "Transfer"
    }
  ]
}

To use specific message notifications with a Soft Token SDK, configure the message table and then set the pushMessageIdentifier as a parameter in the JSON object.

{
  "userId": "jsmith",
  "applicationId": "1111111-111111-111111-11111111",
  "pushMessageIdentifier": "hello"
}

An API response is received after entering the request. For example:

{
  "status": null,
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": false,
    "attributeExclusions": [],
    "userMachineAuthenticators": []
  },
  "kbaChallenge": null,
  "token": "GHldL54iaM9Rn4I4TZ85BzYJVsvxn0sWZxWdUZfFWZxzAawEvJDd4tC9frfvxy6hV7BJDsg2GN3mbxzezsN+AT5tKlX8mPhoWrcUyGYawVxZsbvfmsVesAzNey9RPXyfOvuWqh6BDkpqrL68E1ik+dN50aFK88G4DWxQJ5+oYn0bnarJlLyr4hH62XBCMOmr1T2dTe2SFm+Brj8NI6wKdCnptWAG8QguAlVnXOVntBCzQ/XMFs6ktEnbeCIqXgsUIc2zVd7iXpNMjX5Cl3pgqozCY7UKHFW9WGxFcRz/5+1Y4DuAEGk6VygrdMLV2Hi0UaFN280JQY2jzC1eb6089JOtcm2Rnqi+Zg6OYbzscQfp+o2ARj8IlltQOIgjueiCG5X/AdIbEqc5/nFhbg/d+wNV9M6Fk2bX25iTa6mcIMp2Gvo2mhM8q0ysqzAnXjgveaikymJIx01/q0ctKNCHNN8pgXMF4sNU+GRm2vqdQXcbuTc0krALqtF40QN97JdoBSACUMN4M7gYzFC2SBsArIZwmXAqgCDvzWYq9FhUekgrIr18Bxl7yUFRJLDU",
  "otpdeliveryType": null,
  "expires": 1521484056513,
  "time": 1521483156531
}

Complete Authentication challenge

The user receives a push notification to the device registered with the Entrust Soft Token mobile application. The last step is to complete the authentication process using the token push authenticator. Note that in the push authentication case, there is no response that must be passed to the last API call. The post request should be sent to this API call:

https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/TOKENPUSH/complete

As in the first example, this request will also include an Authorization header field. The Authorization header can be sent with or without a type value of "Bearer". For example:

Authorization: Bearer <token>

Authorization: <token>

The body of this request should contain a JSON object with the ID of the application being accessed. For example:

{
  "applicationId": "1111111-111111-111111-11111111"
}

An API response to the request is received. The response will vary depending on whether the user has completed the push authentication challenge or not. For example, if the user has not yet processed the request, the API response appears as shown:

{
  "status": "NO_RESPONSE",
  "firstName": null,
  "lastName": null,
  "authenticationCompleted": false,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": null,
  "otpdeliveryType": null,
  "expires": 0,
  "time": 1521485352309
}

If the user selected a Confirm response for the push request, the API response appears as shown:

{
  "status": "CONFIRM",
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "machineAuthenticator": null,
  "userMachineSettings": null,
  "kbaChallenge": null,
  "token": "GFu9JJTpgxlAgudDrdm49fxU/sCVVf41jyxM97GDMdHhrqjSwM23bGZt2JBdCWJ/hgo0cq1DN7DYfM74+Xd/EYpMt+Ijn8iWQY2fOohCQLtC4wTJAWkQ2D5iKNGNli3iazbt65mpkqZ7Z5V5krsS1REKLES54jpDjqO4y6a+d8N9SPD8OfQx71cCGf58iDPHm96My2WH/cqvfg0Nl+8NKgtmzpLiG9HayE7KwGqOPlpsQoxuk9Mt6q8z5GL+uZ4zBV8h07KmhWxmFloaJEdJYIqQQbPHrgIZdXNHceGsJjSctkm/68Ib5ZHrtEW/IzHmMDPjau93xP9KB363TTudpO37LlprDBWvjdu+YgkN2ofUO0wsS9aVW9zu/u5LgLLk8WqpX+sS3pWD7naxqpTF0l8+hV7UknTx9n7GEIWlSZnz+5cTJe/qw9n5MXgZMkYhv6aaScKdx+gPlKFqWW7t+8xrvCBX5jybi7qknYsJxjsDnJ9xbfd5AsdE7jdZLkGIrbuh4LeJekz4S3UkC23++9jx99d+OHw9DZjSDAIYx5bApkhPje8wXRwCfHOGq/YuasmwH0lOdOmKVJs51EUbolHfSqVsIXR3SQZqCkVA82yMdYSiY/3Z65mA5EMeyyd0YNXfMGO8nw==",
  "otpdeliveryType": null,
  "expires": 1521486237824,
  "time": 1521485466748
}

If the user selected a Cancel response for the push request, the API response appears as shown:

{
  "errorCode": "no_transaction",
  "errorMessage": "",
  "parameters": null
}

OTP​

Get User's Authenticators​

Select Authenticator​

Complete authentication challenge​

TOKENPUSH​

Get users authenticators​

Select Authenticator​

Complete Authentication challenge​

OTP

Get User's Authenticators

Select Authenticator

Complete authentication challenge

TOKENPUSH

Get users authenticators

Select Authenticator

Complete Authentication challenge