API Multi-Factor Authentication



In this document, we will guide you through the Acreto Multi-Factor Authentication mechanism, as implemented in Acreto API for administrative needs.

Acreto’s Multi-Factor Authentication uses Time-based One-Time Passwords (TOTP) and was tested with the Google Authenticator app.

Acreto’s Multi-Factor Authentication consists of the following steps:

  1. initial configuration
  2. using two-factor authentication


Before you start, you will need to:


In this document, we follow conventions and use variables as defined in API Quick start.

TOTP initial configuration

To configure TOTP multi-factor authentication for a user, you need to follow the following process:

  1. Log in as the user
  2. Generate TOTP keys using POST ​/users​/{username}​/otp endpoint
  3. Add Acreto to your Google Authenticator by scanning generated QR code
  4. Activate multi-factor authentication by providing user-supplied verification code to PATCH ​/users​/{username}​/otp endpoint

Initial configuration example

Generate TOTP keys


curl -X 'POST' \
  'https://api-is-rock-solid.acreto.net/v2/users/user%40email.com/otp' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d ''


  "barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGYUlEQVR4nOyd0Y7bOgxEsxf5/1/uRQu4SAjRHF........rkJggg==",
  "url": "otpauth://totp/Acreto:user@domain.com?algorithm=SHA1&digits=6&issuer=Acreto&period=30&secret=P3YOQUQT1234O2S5FNDOAMMBM7NGFQKG"

Display QR code to the user

 <img src="data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGYUlEQVR4nOyd0Y7bOgxEsxf5/1/uRQu4SAjRHF........rkJggg==" />

Activate MFA using verification code


curl -X 'PATCH' \
  'https://dev-api-never-works.acreto.net/v2/users/user%40email.com/otp' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "123456"

Response: HTTP status 204.

Using multi-factor authentication

To correctly support multi-factor authentication, your app needs to detect HTTP status code 424. Once such a code is received, the app should resend the failed request with an additional HTTP Header, X-OTP, containing TOTP code generated by the TOTP app (Google Authenticator).

Login without one-time password


curl -ik -X 'POST' \
  'https://dev-api-never-works.acreto.net/v2/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "password": "******************",
  "username": "user@domain.com"

Response (with headers):

HTTP/1.1 424 Failed Dependency
Content-Type: application/json
Vary: Origin
X-Request-Id: f4a12ef8-5134-c510-c409-b634ff4e4681
Date: Mon, 10 May 2021 16:31:58 GMT
Content-Length: 146

{"code":16432,"message":"This operation requires multi-factor authentication. Please retry with proper multi-factor authentication infromation."}

As you see, we got HTTP status 424. A request needs to be repeated with X-OTP header included.

Login with one-time password


curl -X 'POST'   'http://localhost:7010/v2/auth/login'   -H 'accept: application/json'   -H 'Content-Type: application/json' -H "X-OTP: 000000"  -d '{
  "password": "******************",
  "username": "user@domain.com"


      {"name":"Some Customer","uuid":"b7921abe-28e8-40aa-b527-00586e2ce3f1"},
      {"name":"Some Customer 2","uuid":"b7921abe-28e8-40aa-b527-00586e2ce3f1"}
Next page: VPN Connection Profile API