Acceptto MFA REST API

Download Acceptto Mobile

If you don't have an Acceptto account and Acceptto mobile application, Download our app and register a new account on it:




Sign into the Acceptto Web Dashboard

Go to our Dashboard Login and Sign In with the account you registered on Acceptto's mobile app. Then go to Applications page: acceptto application page Click on the new application button. It will take you to new application page, for each application you want to integrate with Acceptto you should create an application here. acceptto new application page Set the name of application to whatever you like for example: My Drupal Web site.
Set the redirect URI to:

http://your_domain_name.com/auth/mfa_check

For example, for our showcase website is set to:

http://showcase.acceptto.com/auth/mfa_check.

Set the color to whatever you like, this is the color band user will see next to your application name in Acceptto mobile app. Click in the Create Application button, Now your application is created and you can copy UID, Secret, API Host from here:

acceptto new application created

Calling Authenticate

After whatever method you use in your application for Authentication/Authorization you can use our API as the second factor for validating user identity. For calling authenticate API you need to have UID, Secret that you've created in step 2. Calling authenticate API is as simple as opening a simple link on your browser:

https://mfa.acceptto.com/api/v9/authenticate_with_options?message=My+Application+is+wishing+to+authorize&type=Login&email=acceptto_email_created_on_step_1&uid=uid_you_got_from_step_2&secret=secret_you_got_from_step_2

Authenticate With Options API

Relying party (bank/website/…) calls authenticate in order to get back an authentication channel. Handles a POST request to:

https://mfa.acceptto.com/api/v9/authenticate_with_options

Parameters:

  • message (string) — Custom authentication message that user will see on his mobile device.
  • type (string) — Type of authentication/authorization. User will see this value as the type of transaction on mobile app. for example: Login, Payment, ...
  • email (string) — Email address of Acceptto's user account.
  • uid (string) — Unique identifier of relying party's application
  • secret (string) — Unique secret of relying party's application
  • timeout (int) — (optional parameter) Relying party can specify after how many seconds transaction expires if no response received from user
  • auth_type (int) — (optional parameter) 1 is push, 2 is text, 3 is voice call
  • ip_address (string) — (optional parameter) Relying party can pass the end user's IP address for enabling location based policies and logging.
  • remote_ip_address (string) — (optional parameter) Relying party can pass the end user's remote IP address (IP behind proxy) for enabling location based policies and logging.
  • risk_profile [int] - (optional parameter) Relying party can set the risk_profile to 1,2,3 which means low, medium, high. low is the default risk profile and doesn't do anything, medium risk profile ignores auto accept policies set by user, high risk profile only accepts authorization if user verify his identity by biometric authentication, means user should have one enabled biometric authentication method like fingerprint, face recognition, ...

If you choose auth_type to Push for example user receives a push notification on his device and has timeout seconds to accept/decline. Timeout and auth_type are optional parameters that you can skip, default values are 300 seconds for timeout and auth_type is chosen by user in next step if not specified by you. If your user doesn't have any web context (or is not on a web browser) for example on a SSH session or custom desktop application, you should pass 1 as auth_type so your users will get a push notification on their phones. Then you can skip step 4 and go to step 5 and try to check every few seconds to see if user responded to authorization request on his/her phone.

Returns:

(JSON) - object contains { channel: channel(:string) }

Note: If email is not a valid Acceptto registered email, service will return: {channel: '', message: 'Acceptto email not registered!'}

Channel is an unique identifier that relying party can check later using #check method to see if user responded to transaction on his/her device.

Choosing Authentication Method

After getting authentication channel on step 3, If you are not on web you can skip this step and go to step 5 but if your user is authenticating on a web browser you can redirect user to our page:

https://mfa.acceptto.com/mfa/index?channel=channel_you_got_from_step_3&callback_url=http://your_domain.com/auth/mfa_check

Here user has the option to choose his authentication method between Push Notification, SMS or Voice Call.

  • Push - If user chooses push notification he will get redirected to a countdown page which user has 300 seconds (or 'n' seconds if you specified timeout parameter in step 3) to respond to authorization request on his/her phone.
  • SMS or Voice Call - If user chosen SMS or Voice call he will get redirected to a page that he should enter a passcode. We will deliver passcode to user via voice call or SMS.

After responding to push notification on phone or entering passcode on browser we will redirect back user to the callback_url parameter you specified when redirected user to our page. for example:

http://your_domain_name.com/auth/mfa_check

Then you can proceed to step 5 and check the authorization result via our check API method.

Check Authentication Result

You can check status of transaction by calling check method:

Relying party checks to see if user accepted or declined transaction Handles a POST request to:

https://mfa.acceptto.com/api/v9/check

Parameters:

  • channel (string) — unique identifier that server returned when relying party called #authenticate.
  • email (string) — email address of Acceptto's user account
  • uid (string) — Unique identifier of relying party's application
  • secret (string) — Unique secret of relying party's application

Returns:

(JSON) - object contains { status: auth_status, device_id: (device ID of the device, user used to approve or decline authorization request.) }

The auth_status can be 'approved', 'expired', 'pending' or 'rejected'.

If channel is invalid, the server will return: 'Transaction not found!' as the status.

If auth_status equals pending, device_id will be the device_id of last device used by user.

If user doesn't own a device, device_id will be empty.

Verifying with OTP (for SMS and Voice Call)

If user has chosen to authenticate with SMS or Voice call, You can use this API to verify the OTP (One Time Password) specified by user.

Relying party checks to see if user has entered correct OTP, Handles a POST request to:

https://mfa.acceptto.com/api/v9/otp_verify

Parameters:

  • channel (string) — unique identifier that server returned when relying party called #authenticate.
  • email (string) — email address of Acceptto's user account
  • uid (string) — Unique identifier of relying party's application
  • secret (string) — Unique secret of relying party's application
  • otp (string) — one time password sent to user via sms or voice call

Returns:

(JSON) - object contains { status: #status, message: '' } Returns status of authorization which can be 'approved', 'expired', 'nil' for pending authorization or 'rejected' as well as message returned by verify otp: { status: #status, message: '' }

The status can be 'approved', 'expired', 'nil' for pending authorization or 'rejected'. Note: If channel is invalid, server will return: 'Transaction not found!' as status.

Support

If you require assistance, please email us at support@acceptto.com