New User Authentication API
These API calls are only supported for organizations that are integrated with Active Directory. It will perform just-in-time user provisioning for users that don't have an existing eGuardian account.
Note
For an overview of the Authentication API, including a glossary of terms and prerequisites, see Authentication API.
Authenticating to the API
This REST API uses the OAuth client_credentials
authentication flow.
Get Access Token from the authorization endpoint (/oauth/token
)
Note
This API requires a public scope
.
The client_id
and client_secret
must match the ID and secret of the application the user is attempting to access. Additionally, the same token should be used for all requests to the API endpoint for the same user authentication event.
Parameter | Type | Description |
---|---|---|
grant_type | String |
|
client_id | String | The |
client_secret | String | The client secret for the application in eGuardian |
scope | String | A space-delimited list of scopes to be issued to the access token This API requires a public |
Sample request
{ "grant_type": "client_credentials", "client_id": "YOUR_EGUARDIAN_APPLICATION_UID", "client_secret": "YOUR_EGUARDIAN_APPLICATION_SECRET", "scope": "public" }
This will return the access token if that application is authorized with the requested scopes.
Note
The generated access tokens are more than 255 bytes in length, so when storing them make sure to have at least 500 bytes of storage available or else they will be truncated.
Sample response
{ "access_token": "YOUR_OAUTH_ACCESS_TOKEN", "token_type": "Bearer", "expires_in": 7200, "scope": "public", "created_at": 1630710187 }
Call API endpoint, sending the access token in the Authorization
HTTP header with Bearer
:
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
Authenticate a User
Initiate a user authentication flow.
Header
Field | Type | Description |
---|---|---|
Accept-Language | String | Preferred language for user-facing messages. Default value: |
HTTP-X-ACCEPTTO-RISK-ENGINE | json | JSON string that will be passed to the risk engine and will be available as Note that the name of the parameter might vary based on your deployment configuration. ( |
Request
Method | URL |
---|---|
POST | /api/integration/v2/authn |
Parameters
Field | Type | Description |
---|---|---|
credential_type | String | Type of authentication/authorization. Users will see this value as the event type in the mobile app and elsewhere unless a Allowed values: |
auth_credentials | Object | The credential that will be used for authentication. Internal schema of For more information, see sample requests. |
session_uid | String | A unique identifier for the session. This is the unique value that the relying party should generate for the lifetime of a session and should be unique across the relying party organization between different applications. |
message | String | Message that user receives using push notification on It'sMe app or via text/voice message. |
type | String | Type of authentication/authorization. User will see this value as the type of transaction on mobile app. For example: |
auth_factor | String [] | Array of strings identifying preferred out of band method to be automatically sent to the user (currently only supports first item). The possible values are: |
timeout | Integer | The timeout value for the authentication request in seconds; if the user does not respond within the specified time, the request expires. The default value is 300 seconds (5 minutes). |
ip_address | String | The end user's IP address, to be used for policy-based risk assessment and logging. |
remote_ip_address | String | End user's remote ip address (IP behind proxy) for enabling IP based policies and logging. |
totp | String | Users can be authenticated via TOTP by allowing them to enter their time based one-time passcodes while signing in. When TOTP is specified and is correct, the status of the response is If the TOTP is incorrect, the authentication request will be rejected and no other MFA method will be offered. |
bfpToken | String | The value of the eGuardian® DBFP cookie, if in use. |
response_format | String | Requested response format. Default value: Allowed values: |
Sample request
{ "credential_type": "password_less_login", "auth_credentials": { "username": "abe.lincoln" }, "type": "BillPayment", "auth_factor": [ "push" ], "bfpToken": "a6a5effa4d8c6xxxx123efed89033ab70ae" }
Response
Successful response
Field | Type | Description |
---|---|---|
success | Boolean | Shows whether operation was successful or not. |
response_code | String | Returns response code of |
status | String | Shows status of MFA. The possible values are: |
session_uid | String | A unique identifier for the session. This is the unique value that the relying party should generate for the lifetime of a session and should be unique across the relying party organization between different applications. |
user_email | String | Email address of the user that is authenticating. |
auth_options | Array | Allowed authentication methods for the MFA step. The possible values are: |
expires_at | String | Shows expiry time of MFA in ISO 8601 format. |
notification_type | String | The type of notification that has been sent to the user, if any. |
Successful response example
HTTP/1.1 200 OK { "success": true, "response_code": "success", "channel": "1556910423f49963ade2d1951359b1fe15fcd72c41", "status": "approved/pending/rejected", "session_uid": 10037, "user_email": "abe.lincoln@mailinator.com", "auth_options": ["push", "totp"], "expires_at": "2020-02-11T10:23:57-08:00", "notification_type": null }
Unsuccessful response
Error
Field | Type | Description |
---|---|---|
response_code | String | Normalized response code describing the error type. |
success | String | Generally false. |
message | String | Informative message describing the error. |
Response codes
Field | Type | Description | Response example |
---|---|---|---|
no_authenticator_found | String | No authenticator with the specified type found for the organization. | HTTP/1.1 422 Unprocessable Entity { "content": { "response_code": "no_authenticator_found", "success": false, "message": "Something went wrong, Please contact support@acceptto.com for further assistance." } } |
generic_error | String | If anything else goes wrong, such as a missing parameter or invalid JWT, then a general error message is returned | HTTP/1.1 4XX OK { "response_code": "generic_error", "success": false, "message": "error message" } |
Send Out of Band
Send out of band MFA request to user.
Header
Field | Type | Description |
---|---|---|
Accept-Language | String | Preferred language for user-facing messages. Default value: |
Request
Method | URL |
---|---|
POST | /api/integration/v2/authn/{channel}/factors/{type}/send |
Parameters
Field | Type | Description |
---|---|---|
type | String | Out of band method to be sent to user. Allowed values: |
response_format | String | Requested response format. Default value: Allowed values: |
channel | String | The channel returned from a successful authentication request, uniquely identifying the MFA transaction. |
Response
Successful response
Field | Type | Description |
---|---|---|
response_code | String | Returns response code. The possible values are: |
success | Boolean | Shows whether operation was successful or not. |
status | String | Shows status of MFA. The possible values are: |
expires_at | String | Shows expiry time of MFA in ISO 8601 format. |
notification_type | String | Notification type sent to user. The possible values are: |
message | String | Message that can be shown to end-user. |
Successful response example
HTTP/1.1 200 OK { "response_code": "[otp_type]_sent", "success": true, "status": "pending", "expires_at": "2020-02-11T10:23:57-08:00", "notification_type": "sms/email/call/push", "message": "We just sent you a 6-digit passcode, please check your SMS inbox." }
Unsuccessful response
Error
Field | Type | Description |
---|---|---|
response_code | String | Normalized response code describing the error type. |
success | String | Generally false. |
message | String | Informative message describing the error. |
Response codes
Field | Type | Description | Response example |
---|---|---|---|
mfa_invalid_state | String | Authentication request is no longer valid, no OOB sent. | HTTP/1.1 200 OK { "content": { "response_code": "mfa_invalid_state", "success": false, "message": "Your authentication request is no longer valid, please try to login again.", "expires_at": "2020-02-11T10:23:57-08:00", "notification_type": "sms/email/voice", "status": "expired/rejected/approved" } } |
not_allowed | String | Authentication method not allowed for this application and user. | HTTP/1.1 200 OK { "content": { "response_code": "not_allowed", "success": false, "message": "Authentication method is not allowed for this application and user!", "expires_at": "2020-02-11T10:23:57-08:00", "notification_type": null, "status": "pending" } } |
wait_for_resend | String | Must wait to re-send OOB notification. | HTTP/1.1 200 OK { "content": { "response_code": "wait_for_resend", "success": false, "message": "MFA request rate exceeded. Please wait 22 seconds before requesting a new sms.", "expires_at": "2020-02-11T10:23:57-08:00", "notification_type": "sms", "status": "pending" } } |
tfa_not_found | String | No TFA with the given channel found for this application. | HTTP/1.1 404 Not Found { "content": { "response_code": "tfa_not_found", "success": false, "message": "No authentication request found for this user with the specified channel.", } } |
Verify Factor
Verifies the credential of the chosen authentication factor type.
Header
Field | Type | Description |
---|---|---|
Accept-Language | String | Preferred language for user-facing messages. Default value: |
Request
Method | URL |
---|---|
POST | /api/integration/v2/authn/{channel}/factors/{type}/verify |
Parameters
Field | Type | Description |
---|---|---|
type | String | Factor type being verified. Allowed values: |
response_format | String | Requested response format. Default value: Allowed values: |
channel | String | The channel returned from a successful authentication request, uniquely identifying the MFA transaction. |
Request body
Field | Type | Description |
---|---|---|
factor_response | Object | Object with factor verifier details. |
factor_response.code | String | Authentication factor code. This is the passcode entered by the user to verify the MFA. |
Sample request
{ "factor_response": { "code": "123456" } }
Response
Successful response
Field | Type | Description |
---|---|---|
success | Boolean | Shows whether the API call was successful or not. |
response_code | String | Returns response code of |
status | String | Shows status of MFA. The possible values are: |
message | String | Message that explains success. |
retry_attempts_remaining | Integer | The number of attempts remaining to verify factor. |
Successful response example
HTTP/1.1 200 OK { "response_code": "success", "success": true, "status": "approved", "message": "Your Authorization Request Was Successful!", "retry_attempts_remaining": 3 }
Unsuccessful response
Error
Field | Type | Description |
---|---|---|
response_code | String | Normalized response code describing the error type. |
success | String | Generally false. |
message | String | Informative message describing the error. |
Response codes
Field | Type | Description | Response example |
---|---|---|---|
mfa_invalid_state | String | Authentication request is no longer valid, or OTP not checked. | HTTP/1.1 200 OK { "response_code": "mfa_invalid_state", "success": false, "message": "Your authentication request is no longer valid, please try to login again.", "status": "expired/rejected/approved" } |
invalid_otp | String | Invalid passcode specified. | HTTP/1.1 200 OK { "response_code":"invalid_otp", "success": false, "message":"Invalid passcode was specified, please try again!", "status": "pending", "retry_attempts_remaining": 2 } |
max_retry | String | OTP is invalid and the number of max attempts has been exceeded. TFA is automatically rejected. | HTTP/1.1 200 OK { "response_code": "max_retry", "success": false, "message":"Maximum PIN attempts exceeded. Authorization request denied.", "status": "rejected", "retry_attempts_remaining": 0 } |
tfa_not_found | String | No TFA with the given channel found for this application. | HTTP/1.1 404 Not Found { "response_code": "tfa_not_found", "success": false, "message": "No authentication request found for this user with the specified channel.", } |
Status
Checks and returns authentication result status based on channel.
Header
Field | Type | Description |
---|---|---|
Accept-Language | String | Preferred language for user-facing messages. Default value: |
Request
Method | URL |
---|---|
GET | /api/integration/v2/authn/{channel}/status |
Parameters
Field | Type | Description |
---|---|---|
channel | String | The channel returned from a successful authentication request, uniquely identifying the MFA transaction. |
response_format | String | Requested response format. Default value: Allowed values: |
Response
Successful response
Field | Type | Description |
---|---|---|
success | Boolean | Whether the API call was successful or not. |
response_code | String | Normalized response code describing the error type or "success". |
status | String | Shows status of MFA, possible values pending/expired/approved/rejected. |
channel | String | The channel uniquely identifying the TFA. |
user_id | String | Internal user ID. |
expires_at | String | The TFA expiry in ISO 8601 format. |
session_uid | String | Unique user session identifier. |
Successful response example
HTTP/1.1 200 OK { "success": true, "response_code": "success", "status": "approved/pending/rejected", "channel": "1556910423f49963ade2d1951359b1fe15fcd72c41", "user_id": 3891, "expires_at": "2020-02-11T10:23:57-08:00", "session_uid": "aea7f1d0dd368e448e92ac30a5d8e34d" }
Unsuccessful response
Error
Field | Type | Description |
---|---|---|
response_code | String | Normalized response code describing the error type. |
success | String | Generally false. |
message | String | Informative message describing the error. |
Response codes
Field | Type | Description | Response example |
---|---|---|---|
tfa_not_found | String | No TFA with the given channel found for this application. | HTTP/1.1 404 Not Found { "content": { "response_code": "tfa_not_found", "success": false, "message": "No authentication request found for this user with the specified channel.", } } |
Notification
After initiating an authentication request, the relying party has the option of getting notified as soon as the MFA phase is complete. This can be a result of the user taking action to approve or reject the request or the request having expired.
To listen for the notification, the relying party should use the channel
returned by the initial user authentication request to subscribe to the eGuardian® Faye server. Use the following JavaScript snippet (written using jQuery but vanilla JavaScript works as well).
<script src="https://faye.acceptto.com/faye/faye.js"></script> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script> <script type="text/JavaScript"> $(function() { var faye = new Faye.Client("https://faye.acceptto.com/faye"); faye.subscribe("/messages/<%= @channel %>", function (data) { window.location.reload(); // refresh the page and call check api on refresh }); }); </script>
As soon as the MFA phase is complete, a notification is sent to Faye which relays it to any relying party subscribed to the channel and the code block inside faye.subscribe
executes. Make sure that you are replacing the <%= @channel %>
with the channel
returned by the user authentication call and customize the code block inside faye.subscribe
; the method above simply refreshes the page but generally a redirection to a results page is used.
MFA integration with device browser fingerprint
Use the following steps to integrate MFA with DBFP.
In the body element of your HTML page, add the jQuery library in a script element.
For example, you can include jQuery from a CDN (Content Delivery Network) link in the body element like the following:
<!-- jQuery library (served from Google) --> <script src=“https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js”></script>;
Below the jQuery library script, add the following DBFP JavaScript file script:
<!-- Acceptto DBFP --> <script type="text/JavaScript" src="https://dbfp.acceptto.com/bfp.js"></script> <!-- End Acceptto DBFP --
This script sets a cookie named jwt that can be passed as a parameter to the initial user authentication APIs using the key
bfpToken
orjwt
. eGuardian® uses this data to assess the risk of the authentication request including browser fingerprint, IP address of user and GPS location of the user’s browser. The server compares this data with the history of user behavior data to detect anomalies.Save your changes.