Advanced Authentication API

API Endpoint

Sample Authentication Flow

This is the process to logon a user an get a login_session_id which is required for may other API calls. To logon a device or user to the AA Server:

  • Requires an endpoint id and secret. A single Endpoint may be used to authenticate many users. The endpoint id and secret are returned as a result of creating an Endpoint through one of the following mechanisms

    • Created once via the Admin UI and the endpoint id and secret are securely cached.
    • Created programmatically via the REST API. Create endpoint
  • Create an endpoint session. Create endpoint session

  • Read all chains available for user and event combination. Read user chains

  • Select a chain to attempt if multiple chains are returned.

  • Start logon process Start logon process

  • For each method in the chain perform the following actions:

    • Gather details about data and steps for specific methods. Methods
    • Call do_logon for specific method, the following may be returned:
      • OK: The authentication was successful and the login process has been completed. The returned login_session_id should be securely cached.
      • MORE_DATA: The specific method attempted requires additional data, see specific method descriptions for required data.
      • FAILED: The login attempt was not successful. Start a new logon process to try again.
      • NEXT: This method was successful.
    • After receiving the NEXT return from do_logon, continue chain processing for the following method in the chain by calling next. NEXT method
  • After successfully calling do_logon and NEXT method for every method the caller should recieve OK and a login_session_id

  • Securely cache the returned login_session_id.

Sample Enrollment Flow

Enrollment is the process of setting up the expected response for a particular authentication method. Internally the credential information gathered during enrollment is stored securely in authentication templates. User Templates For some methods the setup is automatic and no user action is required, other methods require that a user manually enroll. Enroll. Enrollment may accomplished by users using the enrollment ui after they authenticate or may be done programmatically via the following steps:

  • Logon with Helpdesk or Authenticators Management events. Sample Authentication

  • Start enroll process Start enroll process

  • Gather details about data and steps for specific methods. Methods

  • Call do_enroll the following status may be returned: + OK: Proceed to ‘Associate the enrollment with a user.’ + FAILED: Process will need start over. Cleanup enroll process + NEXT: Provide requested data.

  • Continue calling do_enroll until the status ‘OK’ or ‘FAILED’ is returned.

  • Associate the enrollment with a user. Create template, fill it from enroll session and link to user The admin may assign the enrollement/template with any user. A user may assign the proccess user to themselves. It is also possible for one user to start the enrollment and hand the enroll_process_id to a second user who then assigns it to themselves.

  • Cleanup if the enroll process is aborted. Cleanup enroll process

Error Handling

Normally the server responds with HTTP status in the 200-299 range and a JSON body (as described in corresponding service). In the case of errors, the HTTP status may be in the 400-599 range. The JSON Response body will be structured as follows.

{
   "errors":[
      {
         "description":"Cannot connect to the LDAP servers",
         "location":"server",
         "msgid":"AUCORE-0047"
      }
   ],
   "reason":"LDAP_NO_CONNECT"
}

Do not use msgid for result status checking, use HTTP status and reason instead.

See Common Do logon for common status codes. Logon methods have additional individual statuses.

Special HTTP Status Codes

HTTP 433 - endpoint session not found or expired. It is possible to get this error in the middle of logon process. You may start new endpoint session, resend do_logon request and continue.

HTTP 434 - logon session not found or expired. Re-logon, get new logon_session_id and then you may continue the operation.

HTTP 444 - logon process not found or expired. Start new logon.

HTTP 400 - wrong data (missed fields etc.) or method protocol violation e.g. voice method already did phone call and wait for PIN code, but you ask it to call user again. Fix your data and retry.

HTTP 500 - serious error, usually not possible to retry. Start your operation from the beginning (open new logon process, etc.)

Additional HTTP Response Status Code information may be found in RFC 7231

Glossary of Terms

Authentication Method

These are the specific authentication methods that are supported by the framework. In order to use a method, it may need to be enrolled, and will need to be connected to a chain. A method without a chain cannot be used to authenticate.

Name Key Authentication by
BankID BANKID:1 BankID PIN
Bluetooth BLUETOOTH:1 Bluetooth devices
Device DEVICE_AUTH:1 Windows TPM (Trusted Platform Module) based virtual smart card
Emergency password EMERG_PASSWORD:1 Alternate/Emergency password
Face FACE:1 Microsoft Cognitive API server
FIDO U2F U2F:1 FIDO U2F tokens
Finger FINGER:1 Fingerprint Biometric
Flex OTP FLEX_OTP:1 Flexible selection of TOTP, HOTP or Smartphone Offline OTP
LDAP password LDAP_PASSWORD:1 LDAP password, system uses different LDAP users repository
OAuth 2.0 OAUTH2:1 OAuth 2.0
One-time password e-mail EMAIL_OTP:1 OTP sending by e-mail
One-time password hash HOTP:1 OTP with hash algorithm
One time password SMS SMS_OTP:1 OTP sending by SMS
One-time password time TOTP:1 OTP with time based algorithm
PKI PKI:1 PKI
RADIUS password RADIUS:1 RADIUS server
Security question SECQUEST:1 Security question
Smartphone authentication SMARTPHONE:1 Smartphone application
Smart Cards CARD:1 Smart Cards
TouchID TOUCHID:1 Apple TouchID
Virtual password PASSWORD:1 Password assigned to user
Voice call VOICE:1 Voice call
Web Authentication WEBAUTH:1 Web services
Windows Hello WINHELLO:1 Windows Hello

For additional information on enrollment and logon to individual methods see here

Chain

An authentication chain is a combination of authentication methods. A user must pass all methods in the chain to be successfully authenticated. For example, if you create a chain with LDAP Password and SMS, a user must first specify the LDAP Password. If the password is correct, the system sends an SMS with a One-Time-Password (OTP) to the user’s mobile. The user must specify the correct OTP to be authenticated.

You can create chains with multiple methods that are applicable for highly secure environments. You can create authentication chains for specific group of users in the repositories.

Enroll

Enrollment is the process of setting up the expected response for a particular authentication method. Internally the credential information gathered during enrollment is stored securely in authentication templates.

Endpoint

Endpoints are used to describe applications, clients, or devices that consume the Advanced Authentication API and provide authentication to users. Common examples of endpoint are computers, smartphones, RADIUS or VPN servers, and web applications.

Endpoint Session

Endpoint should create endpoint session on the server to start working. The endpoint session has a lifetime, after this, the endpoint session will be deleted and the session will need to be renewed. All users can work with one endpoint session on one endpoint.

Event

Advanced Authentication provides authentication events for the supported applications or devices. You can configure an event to leverage the Advanced Authentication functionalities for an application or a device. The application or device triggers the respective authentication event when a user tries to access it.

Logon

The server provides strong user authentication by using the chain-login concept. Each chain is a challenge-response login. To get a successful authentication, the entire chain should be completed. A chain can consist of one or many authentication method(s).

Login session

After a user logon, the system creates a login session, to access protected information from the server use this session. For example, reading event data requires a login session identifier.

Secrets

In addition to credential data, the following fields are all secrets which should be protected by industry standard best practices.

  1. login_session_id
  2. endpoint_session_id
  3. endpoint secret stored on endpoint device, passed as endpoint_secret_hash

Disclosing any of the above fields may allow third parties to read privileged data, impersonate users, or perform other actions behalf of users or endpoints.

User templates

The user’s templates contain authentication information associated with users. Each template is linked to a user and to an authentication method through the enrollment process. When users try to logon using a specific authentication method, the server finds the associated user template and provides authentication. Users cannot use authentication methods without associated user templates.

Localization

It’s possible to choose a locale for server messages and warnings. Server detects a locale for request by the next properties ordered by priority:

  1. HTTP parameter LOCALE for GET or DELETE requests.

  2. JSON attribute LOCALE for POST, PUT and PATCH methods::

  3. LOCALE cookie

  4. Accept-Language HTTP header

  • Request (application/json)

    {
          "login_session_id": "789",
          "method_id": "HOTP:1",
          "_LOCALE_": "ru-RU"
      }

Supported locale formats

  1. Language with territory:

    en_US, nl_NL

  2. Language with territory:

    ru-RU, fr-FR

  3. Language only:

    ru, nl, fr

Message ID

Server issues an additional Message ID which can be used for message customization:

{
    "chains": [],
    "completed_methods": [],
    "current_method": "PASSWORD:1",
    "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
    "msgid": "AUCORE-1008",
    "msg": "Process has been started",
    "status": "MORE_DATA"
}

NOTE: Do not use msgid for result status checking, use status with reason instead.

Advanced Authentication API

Cached Logon notification

This API should be used by desktop clients. It allow them to notify server about cached logons. As result server can

  1. Track such logons to the syslog
  2. Update templates (HOTP counter for example)
  3. Return template hashes which allow clients to clear local cache (if templates was changed since last server logon)

Notify server about cached logon:

POST /api/v1/cached_logon
Requestsexample 1
Body
{
    "endpoint_session" : "a23as...34ff",
    "logons" : [
        {
            "user_name": "TEST\user1",
            "event_name": "Windows Logon",
            "chain_name": "CARD+HOTP",
            "time": "2017-11-23T09:52:30+00:00"
            "secret": "1234...cdef",
            "templates": [ {"id": "4321...fedc", "data": {"counter": 111}, "hash": "1111...2222"} ]
        },
        {
            "user_name": "TEST\user2",
            "event_name": "Windows Logon",
            "chain_name": "FINGER+PIN",
            "time": "2017-11-24T09:52:30+00:00"
            "secret": "1234...cdef"
        }
    ]
}
Responses200
Body
{
    "enrolled_templates": {"TEST\user1": [
        {"id" : <template_id>, "hash": <template hash>, "method_id":"HOTP:1"},
        {"id" : <template_id>, "hash": <template hash>, "method_id":"PASSWORD:1"},
        ],
        "TEST\user2": [
        {"id" : <template_id>, "hash": <template hash>, "method_id":"FINGER:1"},
        {"id" : <template_id>, "hash": <template hash>, "method_id":"CARD:1"},
        ]}
}

Notify server about cached logon:
POST/api/v1/cached_logon

URI Parameters
HideShow
endpoint_session
hex string (required) Example: 'a23as...34ff'

Endpoint session

logons
see below (required) Example: array of 'logon' structures

Information about all cached logons performed since last server logon


Read user templates information:

POST /api/v1/cached_logon/get_user_templates_info
Responses200
Body
{
  "templates_info": [
    {
      "id": "27da61d63c0e1b8a0613aaa63f11c907",
      "enroll_uid": "050acac087e311e996f60242ac110002",
      "counter": 10
    },
    {
      "id": "c9bb14f951c764d416cc88c29579515d",
      "enroll_uid": "051adf2887e311e996f60242ac110002"
    },
    {
      "id": "2d4c23ff1ce496f809e19cc5cb124a09",
      "enroll_uid": "051dcb6687e311e996f60242ac110002",
      "counter": 100
    },
    {
      "id": "dc6aab5d1ab4da2ac1e66c2e4ea6e412",
      "enroll_uid": "0507cca887e311e996f60242ac110002"
    }
  ]
}

Read user templates information:
POST/api/v1/cached_logon/get_user_templates_info

URI Parameters
HideShow
endpoint_session_id
hex string (required) Example: a23as...34ff

Endpoint session

secret
string (required) Example: a23as...34ff

Cache secret

user_name
string (required) Example: a23as...34ff

User name


Chain image

Provides chain images. This API is not restricted by endpoint/logon session.

Load chain image:

GET /api/v1/chain_image/4f34e2882991440ddd0fd515e0d0236c

Load chain image:
GET/api/v1/chain_image/{image_name}

Do not worry about image cache invalidation, possible to cache forever. When admin uploads new image of the chain, ‘chain.image_name’ changes.

Returns:

PNG file, with appropriate content-type and cache settings. You may use it in src attribute of html image.

Returns default image if image_name is default.

URI Parameters
HideShow
image_name
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

value of chain.image-name


POST /api/v1/cookies
RequestsGenerate cookie
Body
{
  "login_session_id": "B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o"
}
Responses200
Body
{
  "server_id": null,
  "cookie_value": "300e82d5d1f31108cd064155728c1dda"
}

Generate cookie value:
POST/api/v1/cookies

Use login_session_id to generate cookie for this session Will return json body with cookie_value and server_id Server_id for single-node configuration is null.


GET /api/v1/cookies/a23as...34ff?server_id=a23as...34ff
Responses200
Body
{
    "user_id": "4f34e2882991440ddd0fd515e0d0236c",
    "user_name": "LOCAL\ADMIN",
    "sid": "GKWrJUBaeBA20KHzHAcmzihNrOgdXooh",
    "repo_id": "3c9c1fd8061e11e6b224080027983191",
    "repo_obj_id": "3caa08a0061e11e6b224080027983191",
    "event_name": "",
    "data_id": ""
}

GET /api/v1/tickets?login_session_id=B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o&target_endpoint_id=a23as...34ff&target_endpoint_name=endpoint name
Responses200
Body
{
  "login_session_data": "296e9f9d8c19d7f9f....2a674855e3f574cb9e272bf68"
}

Custom messages

Read localization items. Requires endpoint_session_id. No writes.

Read all custom messages for category:

GET /api/v1/custom_messages?endpoint_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX&category=messages
Responses200
Body
{
  "items": [
    {
      "key": "errors.access_denied",
      "locale": "en",
      "custom": "",
      "category": "messages",
      "default": "ACCESS DENIED"
    },
    {
      "key": "errors.logon_failed",
      "locale": "en",
      "custom": "",
      "category": "messages",
      "default": "Logon failed"
    },
    {
      "key": "errors.user_not_found",
      "locale": "en",
      "custom": "",
      "category": "messages",
      "default": "User not found"
    }
  ]
}

Read all custom messages for category:
GET/api/v1/custom_messages?endpoint_session_id={endpoint_session_id}&category={category}

Method will return custom messages for specified locale or for english locale by default

Possible category:

  • ‘chains’

  • ‘methods’

  • ‘messages’

URI Parameters
HideShow
category
string (required) Example: messages

Category name

prefix
string (optional) Example: method.ldap

Prefix of key

endpoint_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the endpoint session


Read custom messages item for category and key:

GET /api/v1/custom_messages?endpoint_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX&category=messages&key=errors.logon_failed
Responses200
Body
{
  "key": "errors.logon_failed",
  "locale": "en",
  "custom": "",
  "category": "messages",
  "default": "Logon failed"
}

Read custom messages item for category and key:
GET/api/v1/custom_messages?endpoint_session_id={endpoint_session_id}&category={category}&key={key}

Method will return custom messages for specified locale or for english locale by default

Possible category:

  • ‘chains’

  • ‘methods’

  • ‘messages’

URI Parameters
HideShow
category
string (required) Example: messages

Category name

key
string (required) Example: errors.logon_failed

Custom message key

endpoint_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the endpoint session


Enroll

Enrollment is the process of setting up the expected response for a particular authentication method. Internally the credential information gathered during enrollment is stored securely in authentication templates. User Templates

See Sample Enrollment Flow

Start enroll process:

POST /api/v1/enroll
Requestsexample 1
Body
{
    "method_id": "HOTP:1",
    //login method to create authentication template for
    "login_session_id":"B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o"
}
Responses200
Body
{
  "enroll_process_id": "JfgSCsAr89tR3tu92mKV3MWy4LWSmroU"
}

Start enroll process:
POST/api/v1/enroll

Returns enroll_process_id. Use it in do_enroll method.


Common Do enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect requestIncorrect request
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "secret": "0000000000000100",
    "counter": 10
  }
}
Responses200
Body
{
  "reason": "",
  "method_id": "HOTP:1",
  "status": "OK",
  "msg": ""
}
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "password": "0000000000000100"
  }
}
Responses200
Body
{
  "status": "FAILED",
  "msgid": "AUCORE-3028",
  "reason": "",
  "msg": "Secret and counter are required"
}

Common Do enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Remember enroll_process_id and perform series of do_enroll calls while getting status ‘MORE_DATA’

When you get ‘status’=‘OK’, enroll process is finished. Now you want to create template from process result and link it to a user. POST/PUT enroll_process_id and user_id to ‘user_templates’ service. It will create authentication template and destroy waiting enroll process. User will become template owner.

Details about data and steps for specific methods read here

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process

auth_t_id
string (optional) Example: 83523194b70919672b1157bc929ed67a

enrollment on top of existing authenticator


Destroy pending/waiting process:

DELETE /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX?login_session_id=LRvql8GD946V7ryN8fesWBLhN1I7dpEe

Destroy pending/waiting process:
DELETE/api/v1/enroll/{enroll_process_id}?login_session_id={login_session_id}

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process

login_session_id
string (required) Example: LRvql8GD946V7ryN8fesWBLhN1I7dpEe

ID of the login session


Enroll TOTP

Desktop OTP Tool REST API. Allow user to enroll new TOTP.

Enroll new TOTP:

POST /api/v1/otp-enroll
Responses200200
Body
{
   'status': 'OK',
   'id'; '72fe734607db11e69bae080027983191',
   'category_id': 'f1be127607dc11e69bae080027983191',
   'secret': '5ea77p94xbdfmoqy67n3c76sz64n0o31',
   'is_base32_secret': False,
   'otp_format': 'dec6',
   'period': 30,
   'serial': None,
   'hash': 'sha1'
}
Body
{
    'status': 'FAILED',
    'reason': 'LDAP_PASSWORD_WRONG',
    'msg': 'Invalid credentials'
}

Enroll new TOTP:
POST/api/v1/otp-enroll

URI Parameters
HideShow
tenant_name
string (optional) Example: MARIAGROUP

tenant name of user. ‘TOP’ by default

user_name
string (required) Example: user1

User name with optional repository

password
string (required) Example: 12345

LDAP password for users from LDAP repo, Password AP for users from other repositories

comment
string (optional) Example: 'MY_LAPTOP'

Comment for the enrolled TOTP template.

category_name
string (optional) Example: 'HOME'

Name of category to which enrolled template should belong. None by default.


Remove already enrolled TOTP template:

POST /api/v1/otp-enroll/delete
Responses200200
Body
{
   'status': 'OK'
}
Body
{
    'status': 'FAILED',
    'reason': 'WRONG_SECRET_HASH',
    'msg': 'Wrong secret hash was provided''
}

Remove already enrolled TOTP template:
POST/api/v1/otp-enroll/delete

URI Parameters
HideShow
template_id
string (required) Example: user1

hex-encoded ID of template which should be removed

secret_hash
string (required) Example: '5c...00f'

Endpoints

Endpoint management

Register new endpoint:

POST /api/v1/endpoints
RequestsNot trusted endpointTrusted endpoint
Body
{
    "name": "workstation1.domain.local",  // pass hostname here
    "software_type": "Windows Client",    // PAM Module/AD filter/etc
    "software_ver": "6.0.111",
    "desc": "New NAM endpoint",
    "tenant_name": "MARIA_GROUP",
    "os": {
        // recognized fields
        "type": "Windows",  // Linux, MacOS etc.
        "display_name": "Windows 10 Version 1607",  // Ubuntu 14.04.3 LTS
        "platform": "x64",  // x86 ARM8 etc
        "version": "10.0.14393",  // "14.04.03"
        // Windows machine GUID/SID, Linux machine-id etc.
        // please send GUID as "7c0da94b-ded2-4eb3-9c90-22a568f8d30a",
        // not as "{7c0da94b-ded2-4eb3-9c90-22a568f8d30a}" to slightly improve indexing performance
        "device_id": "<str, unique computer/device ID>",

    // other fields possible - OS specific info
    "build": "14393",
    "tz": "+07:00",
    "win10_version": "1607",
    "RAM": "32768",
    "domain": "WORKGROUP",
    "linux_distr": "Ubuntu",
    "windows_family": "Desktop"
},
"extra": {
    // any extra fields possible
},
"_force": true  // delete conflicting endpoint if any
}
Responses200
Body
{
  "secret": "cctdgkMc4pyKw0jAduP5CetGtaGKniPL",
  "id": "76d1d94607da11e69bae080027983191"
}
Body
{
  "name": "nam.new.trusted.endpoint",
  "typ": 3,
  "desc": "New trusted NAM endpoint2",
  "is_trusted": true,
  "tenant_name": "MARIA_GROUP",
  "auth_data": {
    "method_id": "PASSWORD:1",
    "user_name": "LOCAL\\admin",
    "password": "password"
  }
}
Responses200
Body
{
  "secret": "cJd8UjfftveHW4JXrphTupMDACoF06xZ",
  "id": "72fe734607db11e69bae080027983191"
}

Register new endpoint:
POST/api/v1/endpoints

The result of registering a new new endpoint is an endpoint id and secret. These are privileged materials an should be held securely. Potential methods of secure storage include secure registry storage, privileged-user only accessible file etc.) The endpoint id and secret are used to create endpoint sessions. Create endpoint session The administrator may limit endpoint creation to specific ip addresses meeting allow list criteria.


Read endpoint information:

GET /api/v1/endpoints/f1be127607dc11e69bae080027983191
Responses200404
Body
{
  "name": "nam.new.trusted.endpoint3",
  "typ": 1,
  "desc": "New trusted NAM endpoint",
  "is_enabled": true,
  "id": "d5f5881e07df11e69bae080027983191",
  "is_trusted": true
  // os information is not returned for security reason - this call is world-accessible
}
Body
{
  "errors": [
    {
      "location": "server",
      "name": "AuError",
      "msgid": "AUCORE-1022",
      "description": "Endpoint could not be found"
    }
  ],
  "status": "error"
}

Read endpoint information:
GET/api/v1/endpoints/{endpoint_id}

URI Parameters
HideShow
endpoint_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint


Destroy endpoint:

DELETE /api/v1/endpoints/f1be127607dc11e69bae080027983191
RequestsDelete trusted endpointDelete untrusted endpoint
Body
{
  "auth_data": {
    "method_id": "PASSWORD:1",
    "user_name": "LOCAL\\admin",
    "password": "admin"
  }
}
Responses200
Body
null
Body
{
  "secret": "M2QjVLgxVKOYrpVtYKafsGtKrBRx1aTU"
}
Responses200
Body
null

Destroy endpoint:
DELETE/api/v1/endpoints/{endpoint_id}

Untrusted endpoint can be destroyed by user who knows endpoint’s secret or auth_data Trusted endpoint can be destroyed only by auth_data. Only FULL ADMINS or ENROLL ADMINS can destroy endpoints. This method requires JSON body, not all web clients/proxy servers support body for HTTP DELETE method

auth_data allowed auth methods: PASSWORD:1, LDAP_PASSWORD:1, RADIUS:1, TOTP:1, HOTP:1

URI Parameters
HideShow
endpoint_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint


Update endpoint information:

PATCH /api/v1/endpoints/f1be127607dc11e69bae080027983191
RequestsChange endpoint name
Body
{
    "name":"sara.domain.local",
    "auth_data": {

                    "method_id": "PASSWORD:1",
                    "user_name": "LOCAL\\admin",
                    "password": "admin"
    },
    // optional
    "os": {
        // ... Entire dictionary will be changed
    }
    "software_type": "Windows Client",
    "software_ver": "6.2",
}
Responses200
Body
null

Update endpoint information:
PATCH/api/v1/endpoints/{endpoint_id}

Field auth_data is required to update endpoint

If you omit a field, it will not be changed.

URI Parameters
HideShow
endpoint_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint


Search endpoints by name:

POST /api/v1/endpoints/search
Requestsexample 1
Body
{
  "tenant_name": "MARIA_GROUP",
  "name": "nam.new.trusted.endpoint3",
  "auth_data": {
    "method_id": "PASSWORD:1",
    "user_name": "LOCAL\\admin",
    "password": "admin"
  }
}
Responses200
Body
{
  "endpoints": [
    {
      "name": "nam.new.trusted.endpoint3",
      "typ": 1,
      "desc": "New trusted NAM endpoint",
      "is_enabled": true,
      "id": "d5f5881e07df11e69bae080027983191",
      "is_trusted": true
    }
  ]
}

Search endpoints by name:
POST/api/v1/endpoints/search

Field tenant_name is optional, TOP tenant is used by default. Field name is required, name of endpoint (case-insensitive) Field auth_data is required to search endpoints. Only FULL ADMINS or ENROLL ADMINS can search endpoints.


Endpoint Sessions

Endpoint session management. Required as part of the doLogon process. Authenticated using the endpoint id and endpoint secret returned during endpoint creation. Create endpoint The endpoint secret is never sent back to the server, except as a hash.

Session lifetime (TTL): expire on inactivity 60 min, max lifetime 10080 min. It may change without notice. Please handle 434/433 HTTP codes to re-open session on-the fly and re-send request.

Create endpoint session:

POST /api/v1/endpoints/f1be127607dc11e69bae080027983191/sessions
RequestsSuccessful create sessionCreate session with incorrect credentials
Body
{
    "salt": "i_am_salt",
    "endpoint_secret_hash": "d8065693d119fd3d3b0ea54b31d0bf66cc6b56879de302c94cf0e464fef67124",
    "session_data":
    {
        "any": { "data": ["you", "want to store", "in session"] }
    },

    // Optional - update os and client software information

    "os":
    {
        "display_name": "Ubuntu 14.04.3 LTS",
        "platform": "x64",
        "version": "14.04.03"
        // Entire dictionary will be changed
        // Always pass full info or don't pass any
    },
    "software_type": "Windows Client",  // optional
    "software_ver": "6.2",              // optional
    "name": "new.endpoint.name"  // rename endpoint (e.g if hostname has been changed)
}
Responses200
Body
{
  "endpoint_session_id": "0TbKHn9MsZKJYhfQ0FZ0W2y0RHVwxTOY"
}
Body
{
    "salt": "i_am_salt",
    "endpoint_secret_hash": "d8065693d119fd3d3b0ea54b31d0bf66cc6b56879de302c94cf0e464fef67127",
    //incorrect secret hash
    "session_data": {"any": { "data": ["you", "want to store", "in session"] } }
}
Responses403
Body
{
  "errors": [
    {
      "location": "server",
      "name": "AuError",
      "msgid": "AUCORE-1065",
      "description": "Incorrect credentials (endpoint secret)"
    }
  ],
  "status": "error"
}

Create endpoint session:
POST/api/v1/endpoints/{endpoint_id}/sessions

Client must have endpoint_secret and endpoint_id, they should only be retrieved from a trusted source. The secret is never passed back to the server in clear text, only in hashed+salted form. Server validates and returns endpoint_session_id or HTTP error.

endpoint_secret_hash calculation in python::

def get_endpoint_secret_hash(endpoint, salt):
    # Calculates endpoint secret hash as SHA256(endpoint.secret, SHA256(endpoint.id_hex + salt))
    # salt is random string of length >= 1

    salted_endpoint_id = (endpoint.id_hex + salt).encode('utf-8')
    endpoint_id_hash = sha256(salted_endpoint_id).hexdigest()
    salted_enpoint_secret = (endpoint.secret + endpoint_id_hash).encode('utf-8')

    return sha256(salted_enpoint_secret).hexdigest()
URI Parameters
HideShow
endpoint_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint


Read information about endpoint session:

GET /api/v1/endpoints/f1be127607dc11e69bae080027983191/sessions/f1be127607dc11e69bae080027983191?salt=i_am_salt&endpoint_secret_hash=7a68b11d3e409c09ba1545f5500273defb3c27127250029f00ac65097978fcf6
Responses200
Body
{
  "endpoint_id": "377ac5fe07e011e69bae080027983191",
  "session_data": {
    "any": {
      "data": [
        "you",
        "want to store",
        "in session"
      ]
    }
  },
  "sid": "daTpDaWAd5BP0QzBNcIulLuFYCJ32Aak"
}

Read information about endpoint session:
GET/api/v1/endpoints/{endpoint_id}/sessions/{endpoint_session_id}?salt={salt}&endpoint_secret_hash={endpoint_secret_hash}

URI Parameters
HideShow
endpoint_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint

endpoint_session_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint

salt
string (required) Example: i_am_salt

Client generated salt. This salt is used in secret hash generated algorithm.

endpoint_secret_hash
string (required) Example: 7a68b11d3e409c09ba1545f5500273defb3c27127250029f00ac65097978fcf6

Endpoint secret hash


Destroys the endpoint session:

DELETE /api/v1/endpoints/f1be127607dc11e69bae080027983191/sessions/f1be127607dc11e69bae080027983191?salt=i_am_salt&endpoint_secret_hash=7a68b11d3e409c09ba1545f5500273defb3c27127250029f00ac65097978fcf6
Responses200
Body
null

Destroys the endpoint session:
DELETE/api/v1/endpoints/{endpoint_id}/sessions/{endpoint_session_id}?salt={salt}&endpoint_secret_hash={endpoint_secret_hash}

URI Parameters
HideShow
endpoint_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint

endpoint_session_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint

salt
string (required) Example: i_am_salt

Client generated salt. This salt is used in secret hash generated algorithm.

endpoint_secret_hash
string (required) Example: 7a68b11d3e409c09ba1545f5500273defb3c27127250029f00ac65097978fcf6

Endpoint secret hash


Events

Events manager rest api. Requires login_session_id. Logged user must be member of FULL ADMINS or ENROLL ADMINS.

List of events:

GET /api/v1/events?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "events": [
    {
      "type": "Generic",
      "endpoints": [],
      "chains": [
        {
          "short_name": "",
          "is_enabled": true,
          "methods": [
            "ANY"
          ],
          "is_trusted": null,
          "is_image_custom": false,
          "grace_period": null,
          "name": "Test-chain",
          "id": "4c9f4524608911e7ae720800276d2239",
          "apply_for_ep_owner": false,
          "image_name": "ANY.png",
          "required_chain_id": null,
          "forced": false
        }
      ],
      "is_enabled": true,
      "json_data": {},
      "is_standard": false,
      "is_geo_fencing_enabled": false,
      "category_id": null,
      "geo_zones": [],
      "id": "4c9e8508608911e7ae720800276d2239",
      "name": "TEST",
      "forced": false
    }
  ]
}

List of events:
GET/api/v1/events?login_session_id={login_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

offset
int (optional) Example: 0

offset for pagination, default 0

limit
int (optional) Example: 50

page size, default 50, max 50


Create event:

POST /api/v1/events?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
RequestsSuccessful create generic eventSuccessful create oauth2 event
Body
{
  "name": "Hello, world!",
  "type": "Hello, world!",
  "is_enabled": true,
  "is_geo_fencing_enabled": true,
  "category_id": "Hello, world!",
  "geo_zones": [],
  "chains": [],
  "endpoints": []
}
Schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "event name"
    },
    "type": {
      "type": "string",
      "description": "type of event, one of [\"Generic\",\"OSLogon\",\"PasswordStore\",\"OAuth2\", \"SAML2\"]"
    },
    "is_enabled": {
      "type": "boolean",
      "description": "is event enabled"
    },
    "is_geo_fencing_enabled": {
      "type": "boolean",
      "description": "is geo fencing enabled"
    },
    "category_id": {
      "type": "string",
      "description": "category id"
    },
    "geo_zones": {
      "type": "array",
      "description": "list of geo zones"
    },
    "chains": {
      "type": "array",
      "description": "list of chains"
    },
    "endpoints": {
      "type": "array",
      "description": "list of endpoints"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Responses200
Body
{
  "forced": false,
  "type": "Generic",
  "endpoints": [
    {
      "is_local": false,
      "device_id": "",
      "software_type": "",
      "name": "TEST_ENDPOINT",
      "desc": "",
      "typ": null,
      "owner": null,
      "is_trusted": false,
      "is_enabled": true,
      "id": "56ff565c608a11e7afe10800276d2239"
    }
  ],
  "is_standard": false,
  "is_enabled": false,
  "category_id": null,
  "is_geo_fencing_enabled": false,
  "name": "TEST_EVENT2",
  "chains": [
    {
      "apply_for_ep_owner": false,
      "image_name": "default",
      "required_chain_id": null,
      "is_enabled": true,
      "forced": false,
      "name": "chain",
      "grace_period": null,
      "short_name": "",
      "id": "56ff8384608a11e7afe10800276d2239",
      "is_image_custom": false,
      "methods": [
        "OTP:1",
        "PASSWORD:1"
      ],
      "is_trusted": null
    }
  ],
  "json_data": {},
  "geo_zones": [],
  "id": "59704798608a11e7afe10800276d2239"
}
Body
{
  "name": "OAUTH_EVENT",
  "type": "OAuth2",
  "chains": [],
  "category_id": null,
  "endpoints": [],
  "json_data": {
    "oauth2_appid": "id-5wHqLd41D3Z9WUXKcHKjEPk02GHhRJAb",
    "oauth2_appsecret": "secret-QnrJFOw32IFHDW1bYWR8TJCl1psDEOkr",
    "oauth2_redir_uris": "https://test1"
  }
}
Responses200
Body
{
  "forced": false,
  "id": "f38595d2616511e7ae230800276d2239",
  "name": "OAUTH_EVENT",
  "category_id": null,
  "is_geo_fencing_enabled": false,
  "is_standard": false,
  "geo_zones": [],
  "endpoints": [
    {
      "owner": null,
      "is_trusted": true,
      "typ": null,
      "device_id": "",
      "desc": "OSP Endpoint",
      "id": "43434343434343434343434343434343",
      "name": "OSP",
      "is_local": true,
      "is_enabled": true,
      "software_type": "BuiltinOSP"
    }
  ],
  "chains": [],
  "is_enabled": false,
  "type": "OAuth2",
  "json_data": {
    "oauth2_redir_uris": "https://test1",
    "oauth2_appsecret": "secret-QnrJFOw32IFHDW1bYWR8TJCl1psDEOkr",
    "oauth2_appid": "id-5wHqLd41D3Z9WUXKcHKjEPk02GHhRJAb"
  }
}

Create event:
POST/api/v1/events?login_session_id={login_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


Get event by event id:

GET /api/v1/events/59704798608a11e7afe10800276d2239?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "type": "Generic",
  "endpoints": [],
  "chains": [
    {
      "short_name": "",
      "is_enabled": true,
      "methods": [
        "ANY"
      ],
      "is_trusted": null,
      "is_image_custom": false,
      "grace_period": null,
      "name": "Test-chain",
      "id": "4c9f4524608911e7ae720800276d2239",
      "apply_for_ep_owner": false,
      "image_name": "ANY.png",
      "required_chain_id": null,
      "forced": false
    }
  ],
  "is_enabled": true,
  "json_data": {},
  "is_standard": false,
  "is_geo_fencing_enabled": false,
  "category_id": null,
  "geo_zones": [],
  "id": "4c9e8508608911e7ae720800276d2239",
  "name": "TEST",
  "forced": false
}

Get event by event id:
GET/api/v1/events/{event_id}?login_session_id={login_session_id}

URI Parameters
HideShow
event_id
string (required) Example: 59704798608a11e7afe10800276d2239

ID of the event

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


Update event:

PUT /api/v1/events/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
RequestsSuccessful update session
Body
{
  "name": "Hello, world!",
  "type": "Hello, world!",
  "is_enabled": true,
  "is_geo_fencing_enabled": true,
  "category_id": "Hello, world!",
  "geo_zones": [],
  "chains": [],
  "endpoints": []
}
Schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "event name"
    },
    "type": {
      "type": "string",
      "description": "type of event, one of [\"Generic\",\"OSLogon\",\"PasswordStore\",\"OAuth2\", \"SAML2\"]"
    },
    "is_enabled": {
      "type": "boolean",
      "description": "is event enabled"
    },
    "is_geo_fencing_enabled": {
      "type": "boolean",
      "description": "is geo fencing enabled"
    },
    "category_id": {
      "type": "string",
      "description": "category id"
    },
    "geo_zones": {
      "type": "array",
      "description": "list of geo zones"
    },
    "chains": {
      "type": "array",
      "description": "list of chains"
    },
    "endpoints": {
      "type": "array",
      "description": "list of endpoints"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Responses200
Body
{
  "is_geo_fencing_enabled": false,
  "forced": false,
  "type": "Generic",
  "json_data": {},
  "id": "a131020c608a11e7a1810800276d2239",
  "geo_zones": [],
  "chains": [],
  "category_id": null,
  "is_enabled": false,
  "name": "TEST2",
  "is_standard": false,
  "endpoints": [
    {
      "is_local": false,
      "software_type": "",
      "is_trusted": false,
      "desc": "",
      "typ": null,
      "is_enabled": true,
      "device_id": "",
      "name": "TEST_ENDPOINT",
      "owner": null,
      "id": "a135281e608a11e7a1810800276d2239"
    }
  ]
}

Update event:
PUT/api/v1/events/{event_id}?login_session_id={login_session_id}

URI Parameters
HideShow
event_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the event

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


Delete event:

DELETE /api/v1/events/59704798608a11e7afe10800276d2239?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

Delete event:
DELETE/api/v1/events/{event_id}?login_session_id={login_session_id}

URI Parameters
HideShow
event_id
string (required) Example: 59704798608a11e7afe10800276d2239

ID of the event

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


Logon

Implements logon process. See Sample Logon Flow

Login procedure:

  1. Requires endpoint_session_id be passed on all requests.

  2. Start login process Start logon process

  3. Series of do_logon calls. Client software sends ‘response’ to server; server replies with ‘challenge’

  4. Received status=‘OK’ or ‘FAILED’ is the end of the process.

    OK - logon is complete, login session has been created. FAILED - logon failed, the process destroyed (note - HTTP status is 200).

  5. HTTP errors 400 or 500 do not destroy the process, it is possible to continue.

  6. Special HTTP error 444 is returned in case when logon process not found or expired. Not possible to continue. Start new logon.

  7. Special HTTP error 434 is returned in case when login session not found or expired. (433 is same for endpoint session)

Simple logon

First, create login process::

POST /api/v1/logon
    {
        "method_id": "PASSWORD:1",
        "user_name": "REPONAME\\USERNAME",
        "is_1N": true/false,   # optional, default false
        "unit_id": "xxx",   # for 1N login
        "event": "xxx"   # can be empty string for testing (allow any method)
    }

For 1N login, set is_1N to True and pass unit_id. For normal login, pass user_name.
Return::

{
    "chains": [],
    "completed_methods": [],
    "current_method": "PASSWORD:1",
    "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
    "msg": "Process has been started",
    "status": "MORE_DATA"
}

Remember logon_process_id and perform series of do_logon calls while getting status ‘MORE_DATA’::

POST /api/v1/logon/Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa/do_logon
    {
        "response": "method-specific dictionary, maybe omitted if method does not requires data on 1st do_login"
    }

Return
    {
        # method-specific data such as
        "challenge": {"rounds": 100, "salt": "cdf123Dx"},
        "status": "MORE_DATA"
    }
POST /api/v1/logon/Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa/do_logon
    {
        "response": {"answer" : "my-password" # method-specific dict in "response" field}
                                              # this is "response" to "challenge" which server sent in previous do_logon
    }

At some iteration, server will retrun either status=OK or FAILED. ‘OK’ provides additional information about authenticated user::

{ 
    "chains": [],
    "completed_methods": ["PASSWORD:1"],
    "login_session_id": "YTxTmMW6RPv051RmeCiyBn7txzE0JoM2",
    "msg": "Welcome",
    "repo_id": "703f7c641beb11e48c69000c294fde0e",
    "user_id": "7044631e1beb11e48c69000c294fde0e"
    "user_name": "LOCAL\\\\user1",
    "event_name": "Windows logon",
    "event_data_id": "OSLogon",
    "status": "OK",
    "completed_chain": {
        "name": "Admin Password",
        "position": 0,
        "id_hex": "3c8c306e061e11e6b224080027983191",
        "apply_for_ep_owner": false,
        "required_chain_id_hex": null,
        "methods": ["PASSWORD:1"],
        "short_name": "",
        "image_name": "PASSWORD_1.png",
        "is_trusted": null,
        "is_enabled": true,
        "grace_period": null,
        "mfa_tags" : []
    }
}

Example of FAILED method

{ 
    "msg": "Incorrect password",
    "status": "FAILED"
}

Remember login_session_id, it is required for other REST API calls. 1-N logon does not know user name before login starts, and now it knows.

Chained logon

Read user chains Depending on event and endpoint_session_id (trusted/untrusted endpoint) the response is a list of chains.

A Chain defines a list of methods user must login to, one-by-one.

  • After login, data of the event may be accessed using User data service.

‘NEXT’ status says that current method is complete (OK) and user must start next method. Which method to start is up to user (or client UI) - it depends on which chain the user wants to complete.

Login is completed as soon as any chain is completed.

Chained logon example::

optional - read chains

GET  /api/v1/logon/chains?event=Windows%20logon&is_trusted=true

decide what chain to complete and...
  1. Start 1st method.
POST /api/v1/logon
    { "method_id": "SUPER_OTP:1", "user_name": "MARIA\\director", "event": "Windows logon" }
    
returns
    { "chains":
            [
                # same list of chains as you GET from /api/v1/logon/chains?event=Windows%20logon
            ],
      "completed_methods": [],
      "current_method": "SUPER_OTP:1",
      "logon_process_id": "abc345",
      "msg": "Process has been started",
      "status": "MORE_DATA"
    }

Remember login_process_id (abc345) and…

  1. Call do_logon.
POST /api/v1/logon/abc345/do_logon
    { "response": "some_secret" }
    
returns
    { "status": "MORE_DATA", "current_method": "SUPER_OTP:1", "completed_methods": [] }
  1. Continue 1st method (it is 2-phase method).
POST /api/v1/logon/abc345/do_logon
    { response: "second_secret" }
    
returns
    { status: "NEXT", "completed_methods": ["SUPER_OTP:1"] }

Status=NEXT means ‘SUPER_OTP’ is OK, completed_methods has method name.
You start next method by POSTing to same process::

  1. Start next method.
POST /api/v1/logon/abc345/next
    { "method_id": "LDAP_PASSWORD:1" } # user_name will be same as before
                                       # you may pass unit_id and is_1N=true,
                                       # it will work - but unit_id must be owned by same user
                                       
returns
    { status: "MORE_DATA", "current_method": "LDAP_PASSWORD:1", "completed_methods": ["SUPER_OTP:1"]}
  1. Call do_logon.
POST /api/v1/logon/abc345/do_logon
    { "response": "Password1" }
    
returns
    {
        "status": "OK",
        "completed_methods": ["SUPER_OTP:1", "LDAP_PASSWORD:1"],
        "login_session_id": "YTxTmMW6RPv051RmeCiyBn7txzE0JoM2",
        "msg": "Welcome",
        "repo_id": "703f7c641beb11e48c69000c294fde0e",
        "user_id": "7044631e1beb11e48c69000c294fde0e",
        "user_name": "MARIA_GROUP\\user1",
        "event_name": "Windows logon",
        "event_data_id": "OSLogon",
        "completed_chain": {
            "name": "Admin Password",
            "position": 0,
            "id_hex": "3c8c306e061e11e6b224080027983191",
            "apply_for_ep_owner": false,
            "required_chain_id_hex": null,
            "methods": [
            "PASSWORD:1"
            ],
            "short_name": "",
            "image_name": "PASSWORD_1.png",
            "is_trusted": null,
            "is_enabled": true,
            "grace_period": null,
            "mfa_tags" : []
            }
    }

The chain is complete! remember the login_session_id and user info.

Chained logon - wrong password in the middle

Consider a chain that has 3 methods, the user completed 2 of them but provided wrong credentials for 3rd method. In that case:

  1. Result is NEXT, if FAILED had been returned that would have been the endo of the process.

  2. The completed_methods still contains 2 methods.

  3. Re-start method by POSTing as usual to /api/v1/logon/abc345/next

Multi method logon

For methods that support multi method logon - logon works as usual logon except user can use any of templates(otp tokens, passwords, cards)

For methods that don’t support multi method logon we should provide category_id.

Server returns categories list(categories) during start/next methods and id of one of them should be provided as body param during do_logon method.

  1. Start 1st method.
POST /api/v1/logon
    { "method_id": "SUPER_OTP:1", "user_name": "MARIA\\director", "event": "Windows logon" }
    
returns
    { "chains": [...],
      "completed_methods": [],
      "current_method": "SUPER_OTP:1",
      "logon_process_id": "abc345",
      "msg": "Process has been started",
      "status": "MORE_DATA",
      "categories": [
          {"id": "37f81490f3e711e9b5590242ac110002", "name": "CATEGORY1", "desc": ""}, 
          {"id": "", "name": "Default category", "desc": "Default category"}, 
          {"id": "37fb6ee2f3e711e9b5590242ac110002", "name": "CATEGORY2", "desc": ""}
        ]
    }

Remember login_process_id (abc345) and category_id(“37f81490f3e711e9b5590242ac110002” for example) …

  1. Call do_logon and it returns current_category_id as current category used for logon.
POST /api/v1/logon/abc345/do_logon
    { "response": "some_secret", "category_id":"37f81490f3e711e9b5590242ac110002" }
    
returns

{
        "status": "OK",
        "completed_methods": ["SUPER_OTP:1", "LDAP_PASSWORD:1"],
        "login_session_id": "YTxTmMW6RPv051RmeCiyBn7txzE0JoM2",
        "msg": "Welcome",
        "repo_id": "703f7c641beb11e48c69000c294fde0e",
        "user_id": "7044631e1beb11e48c69000c294fde0e",
        "user_name": "MARIA_GROUP\\user1",
        "event_name": "Windows logon",
        "event_data_id": "OSLogon",
        "current_category_id": "37f81490f3e711e9b5590242ac110002".
        "completed_chain": {
            "name": "Admin Password",
            "position": 0,
            "id_hex": "3c8c306e061e11e6b224080027983191",
            "apply_for_ep_owner": false,
            "required_chain_id_hex": null,
            "methods": [
            "PASSWORD:1"
            ],
            "short_name": "",
            "image_name": "PASSWORD_1.png",
            "is_trusted": null,
            "is_enabled": true,
            "grace_period": null,
            "mfa_tags" : []
            }
    }

The chain is complete! Grab login_session_id!

OK, grab login_session_id and user info.

Create logon process:

POST /api/v1/logon
RequestsSimple logon1:N authentication
Body
{
  "method_id": "PASSWORD:1",
  "user_name": "LOCAL\\USER1",
  "event": "NAM",
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u"
}
Responses200
Body
{
  "completed_methods": [],
  "chains": [
    {
      "name": "Authenticators Management - Password",
      "position": 1,
      "id_hex": "3c927b4a061e11e6b224080027983191",
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "PASSWORD:1"
      ],
      "short_name": "",
      "image_name": "PASSWORD_1.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "plugins": [],
  "event_name": "NAM",
  "logon_process_id": "TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS",
  "event_data_id": "OSLogon",
  "status": "MORE_DATA",
  "msgid": "AUCORE-1008",
  "current_method": "PASSWORD:1",
  "msg": "Process has been started",
  "reason": "PROCESS_STARTED"
}
Body
{
        "method_id": "PASSWORD:1",
        "event": "NAM",
        "is_1N":true,
        "unit_id":"test",
        "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
    }
Responses200
Body
{ 'chains': [],
  'completed_methods': [],
  'current_method': 'PASSWORD:1',
  'logon_process_id': 'Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa',
  'msg': 'Process has been started',
  'status': 'MORE_DATA'
}

Create logon process:
POST/api/v1/logon

First, you create login process For 1N login, you set is_1N to True and pass unit_id. For normal login, you pass user_name. Then use doLogon method to proceed.

Use next event names as event param:

  • Authenticators Management

  • EndpointsManagement

  • NAM

  • NCA

  • AdminUI

  • Radius Server

  • Helpdesk

  • Mac OS logon

  • Windows logon

  • ADFS

  • Linux logon

  • Report logon

  • Helpdesk user

  • Search Card

  • Tokens Management

  • Authentication Agent

  • Mainframe Logon

  • Desktop OTP Tool

  • Smartphone Enrollment

  • SCIM API


Common Do logon

POST /api/v1/logon/TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS/do_logon
RequestsSimple virtual password doLogonSimple incorrect virtual password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "my-password"
  }
}
Responses200
Body
{
  "user_id": "4f34e2882991440ddd0fd515e0d0236c",
  "completed_methods": [
    "PASSWORD:1"
  ],
  "repo_id": "3c9c1fd8061e11e6b224080027983191",
  "status": "OK",
  "repo_obj_id": "3caa08a0061e11e6b224080027983191",
  "event_data_id": "",
  "logon_process_id": "jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "TmPxkC98vF4FGhDvqedjXItbmGjVJYTD",
  "plugins": [],
  "event_name": "",
  "chains": [
    {
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "ANY"
      ],
      "short_name": "",
      "image_name": "ANY.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "current_method": "PASSWORD:1",
  "msgid": "AUCORE-2001",
  "msg": "Welcome",
  "data_id": "",
  'completed_chain': {
      "name": "TEST CHAIN",
      "position": 0,
      "id_hex": "3c8c306e061e11e6b224080027983191",
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
      "PASSWORD:1"
      ],
      "short_name": "",
      "image_name": "PASSWORD_1.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null,
      'mfa_tags' : []
  }
}
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "my-incorrect-password"
  }
}
Responses200
Body
{
  "completed_methods": [],
  "chains": [
    {
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "ANY"
      ],
      "short_name": "",
      "image_name": "ANY.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "plugins": [],
  "event_name": "",
  "logon_process_id": "TaEXATdeJmyzhYlEKDwBKCUqzMW0YdtT",
  "event_data_id": "",
  "status": "FAILED",
  "msgid": "AUCORE-2007",
  "current_method": "PASSWORD:1",
  "msg": "Incorrect password",
  "reason": "PASSWORD_WRONG"
}

Common Do logon
POST/api/v1/logon/{logon_process_id}/do_logon

Remember logon_process_id and perform series of do_logon calls while getting status ‘MORE_DATA’

doLogon response can contain status with OK, FAILED, MORE_DATA, NEXT

OK - you are successfully logged to event

FAILED - unsuccessful response for logon

NEXT - current method is done, service is waiting for next method. To start next method use next method below. Then call do_logon, as usual.

MORE_DATA - service is waiting for data

At some iteration, you get either status=OK or FAILED.

‘OK’ gives you also information about logged user. Remember login_session_id, it is used for most REST API calls.

Details about data and steps for specific methods read here

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS

ID of the logon process


Continue logon for multiple step logon

POST /api/v1/logon/TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS/next
Requestsexample 1
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "method_id": "HOTP:1"
}
Responses200
Body
{
  "event_name": "",
  "completed_methods": [
    "PASSWORD:1"
  ],
  "msg": "Process has been started",
  "chains": [
    {
      "required_chain_id_hex": null,
      "short_name": "",
      "position": 0,
      "apply_for_ep_owner": false,
      "id_hex": "e5c25e240a2411e68f20080027983191",
      "methods": [
        "PASSWORD:1",
        "HOTP:1"
      ],
      "is_enabled": true,
      "is_trusted": null,
      "grace_period": null,
      "name": "test",
      "image_name": "default"
    }
  ],
  "current_method": "HOTP:1",
  "plugins": [],
  "msgid": "AUCORE-1008",
  "reason": "PROCESS_STARTED",
  "status": "MORE_DATA",
  "event_data_id": "",
  "logon_process_id": "TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS"
}

Continue logon for multiple step logon
POST/api/v1/logon/{logon_process_id}/next

For example: after successful PASSWORD:1 logon

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS

ID of the logon process


Read available chains:

GET /api/v1/logon/chains?user_name=LOCAL\USER1&is_trusted=1&event=NAM&endpoint_session_id=f1be127607dc11e69bae080027983191&include_all_chains=True
Responses200
Body
{
  "chains": [
    {
      "name": "Admin Password",
      "position": 0,
      "id_hex": "3c8c306e061e11e6b224080027983191",
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "PASSWORD:1"
      ],
      "short_name": "",
      "image_name": "PASSWORD_1.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null,
      'mfa_tags' : []
    },
    {
      "name": "Authenticators Management - Password",
      "position": 2,
      "id_hex": "3c927b4a061e11e6b224080027983191",
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "PASSWORD:1"
      ],
      "short_name": "",
      "image_name": "PASSWORD_1.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null,
      'mfa_tags' : []
    }
  ],
  "user_is_locked": false
}

Read available chains:
GET/api/v1/logon/chains?user_name={user_name}&is_trusted={is_trusted}&event={event}&endpoint_session_id={endpoint_session_id}&include_all_chains={include_all_chains}

is_trusted can be 1, 0, “True”, “False” or missed(False)

If you omit ‘is_trusted’ in your query, service does not filter and returns both trusted and untrusted chains.

If you omit ‘user_name’, service does not filter and returns all chains configured given event/is_trusted.

If you provide ‘user_name’ of user that isn’t yet registered in aucore (such as new LDAP user), service returns only chains made of methods not requiring enroll.

include_all_chains can be 1, 0, “True”, “False” or missed(False)

If you set include_all_chains to True, service will return chains, even dependant or short

“user_is_locked” returned if you specify user_name, use it to immediately show error and not ask user creds / chain selection

URI Parameters
HideShow
is_trusted
boolean (required) Example: 1

Show only trusted chains or not (1, 0, “True”, “False”)

user_name
string (required) Example: LOCAL\USER1

username

event
string (required) Example: NAM

event’s name

endpoint_session_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint

include_all_chains
string (required) Example: True

Destroy logon process:

DELETE /api/v1/logon/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX?endpoint_session_id=f1be127607dc11e69bae080027983191

Destroy logon process:
DELETE/api/v1/logon/{logon_process_id}?endpoint_session_id={endpoint_session_id}

URI Parameters
HideShow
logon_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the logon process

endpoint_session_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint


Logon by Basic Auth to /account

Provides basic authentication.

Authenticate by basic authentication header:

GET /account/basic
Requestsauthorization by PASSWORD:1
Headers
Authorization: Basic <base64 of credentials>
Responses302
Headers
Location: /account

Authenticate by basic authentication header:
GET/account/basic

Credentials format:

login:method_name:password

Examples:

  • Authorization: {base64 of REPO\user1:LDAP_PASSWORD:1:user1_password}

  • Authorization: {base64 of TENANT\REPO\user1:HOTP:1:user1_password}

  • Authorization: {base64 of user1:HOTP:1:user1_password}


Login Sessions

Manage login sessions. Requires endpoint_session_id

Session lifetime (TTL): expire on inactivity 20 min, max lifetime 1440 min. It may change without notice. Please handle 434/433 HTTP codes to re-open session on-the fly and re-send request.

Read information about login session:

GET /api/v1/logon/sessions/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX?endpoint_session_id=f1be127607dc11e69bae080027983191
Responses200
Body
{
    "user_id": "4f34e2882991440ddd0fd515e0d0236c",
    "user_name": "LOCAL\ADMIN",
    "sid": "GKWrJUBaeBA20KHzHAcmzihNrOgdXooh",
    "repo_id": "3c9c1fd8061e11e6b224080027983191",
    "repo_obj_id": "3caa08a0061e11e6b224080027983191",
    "event_name": "",
    "data_id": "",
    "chain_id" : "3cab08a0061e11e6b224080027983191"
}

Read information about login session:
GET/api/v1/logon/sessions/{login_session_id}?endpoint_session_id={endpoint_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

endpoint_session_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint session

nested_groups: (optional, boolean) - Extend the user_groups list with any parent groups.
string (required) 

Delete login session:

DELETE /api/v1/logon/sessions/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX?endpoint_session_id=f1be127607dc11e69bae080027983191

Delete login session:
DELETE/api/v1/logon/sessions/{login_session_id}?endpoint_session_id={endpoint_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

endpoint_session_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the endpoint session


Logon domains associated with this tenant

Read and update logon domains associated with this tenant

Register logon domains for the current tenant:

PUT /api/v1/logondomains
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "login_session_id": "B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o",
  "domains": [
    {
      "name": "test.com"
    },
    {
      "name": "example.com"
    }
  ]
}
Responses200
Headers
Content-Type: application/json
Body
null

Register logon domains for the current tenant:
PUT/api/v1/logondomains

Replaces any existing logon domains with the passed domains


Logon domains lookup

POST /api/v1/logondomains/get] [POST /api/v1/logondomains/get
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "login_session_id": "JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "domains": [
    {
      "name": "foo.example.com"
    },
    {
      "name": "bar.example.com"
    }
  ]
}

Logon domains lookup
POST/api/v1/logondomains/get] [POST /api/v1/logondomains/get

Reads any existing logon domains


Methods

BANKID:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
Requestsexample 1
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "personal_id": "123456789123"
  }
}
Responses200
Body
{
  "reason": "",
  "method_id": "BANKID:1",
  "status": "OK",
  "msg": ""
}

BANKID:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with personal ID number to do_enroll and check status.

Error reasons:

  • MISSING_PERSONAL_ID_NUMBER

  • INVALID_PERSONAL_ID_NUMBER

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


BANKID:1 logon :

POST /api/v1/logon/tvV9a4UNEf71yvZDxwJQ179SJnHQndmT/do_logon
Requests1. Send request to BankID App2a. Finish logon successfully2b. Finish logon failed
Body
{
  "endpoint_session_id": "MDG133vYLaZIBuSvHFF5LfZtSApQHkaQ"
}
Responses200
Body
{
  "reason": "WAITING_FOR_USER_ACCEPT",
  "msg": "Start your BankID app",
  "chains": [
    {
      "id_hex": null,
      "is_enabled": true,
      "short_name": "",
      "grace_period": null,
      "image_name": "BANKID_1.png",
      "is_trusted": null,
      "name": "Test-chain",
      "methods": [
        "BANKID"
      ],
      "apply_for_ep_owner": false,
      "position": 1000,
      "required_chain_id_hex": null
    }
  ],
  "current_method": "BANKID:1",
  "status": "MORE_DATA",
  "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
  "event_name": "TEST",
  "completed_methods": [],
  "event_data_id": "",
  "plugins": [],
  "method_id": "BANKID:1"
}
Body
{
  "endpoint_session_id": "MDG133vYLaZIBuSvHFF5LfZtSApQHkaQ"
}
Responses200
Body
{
    "data_id": "",
    "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
    "current_method": "BANKID:1",
    "event_data_id": "",
    "user_id": "3a76753d7f931751c79fa05d80eb058e",
    "repo_id": "42987aa00c8911e69140080027983191",
    "msgid": "AUCORE-2001",
    "plugins": [],
    "repo_obj_id": "42a3962e0c8911e69140080027983191",
    "event_name": "TEST",
    "msg": "Welcome",
    "chains": [
        {
            "short_name": "",
            "required_chain_id_hex": null,
            "position": 0,
            "is_enabled": true,
            "methods": ["BANKID:1"],
            "image_name": "BANKID_1.png",
            "grace_period": null,
            "name": "Test-chain",
            "id_hex": "42b312980c8911e69140080027983191",
            "apply_for_ep_owner": false,
            "is_trusted": null
        }
    ],
    "user_name": "LOCAL\USER1",
    "completed_methods": ["BANKID:1"],
    "status": "OK",
    "login_session_id": "Cga6cvaMTaMTaDp5TLZHPOet29O808VL"
}
Body
{
  "endpoint_session_id": "MDG133vYLaZIBuSvHFF5LfZtSApQHkaQ"
}
Responses200
Body
{
  "event_name": "TEST",
  "current_method": "BANKID:1",
  "status": "FAILED",
  "reason": "ERROR",
  "method_id": "BANKID:1",
  "completed_methods": [],
  "msg": "Action cancelled",
  "plugins": [],
  "chains": [
    {
      "grace_period": null,
      "image_name": "BANKID_1.png",
      "position": 1000,
      "apply_for_ep_owner": false,
      "id_hex": null,
      "short_name": "",
      "is_trusted": null,
      "methods": [
        "BANKID"
      ],
      "is_enabled": true,
      "required_chain_id_hex": null,
      "name": "Test-chain"
    }
  ],
  "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
  "event_data_id": ""
}

BANKID:1 logon :
POST/api/v1/logon/{logon_process_id}/do_logon

  1. Send empty request to do_logon to send the notification to BankID App. User should receive notification in the BankID app and he can Identify or Cancel it.

  2. To check status of logon application should send empty request to do_logon until status will not changed for failed or successful.

Error reasons:

  • OK

  • WRONG_STATE

  • WAITING_FOR_USER_ACCEPT

  • ERROR

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: tvV9a4UNEf71yvZDxwJQ179SJnHQndmT

ID of the logon process


BLUETOOTH:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsBluetooth enroll
Body
{
  "response": {
    "address": "aabbccdd",
    "name": "Bluetooth device"
  },
  "login_session_id": "KOYxcRUuuZxDsEhxiycof4XwcuI2lbwk"
}
Responses200
Body
{
  "method_id": "BLUETOOTH:1",
  "status": "OK",
  "reason": "",
  "msg": "Enrollment is complete",
  "msgid": "AUCORE-3001"
}

BLUETOOTH:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with mac address and device name to do_enroll

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


BLUETOOTH:1 logon:

POST /api/v1/logon/do_logon
Requests1. Ask server for encrypted mac address2. Send mac address of enrolled device from Device Service to do_logon
Body
{
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
    "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
    "current_method": "BLUETOOTH:1",
    "reason": "BLUETOOTH_WAITING_AUTH_RESPONSE",
    "event_data_id": "",
    "msgid": "AUCORE-2059",
    "plugins": [],
    "hashes": [
        '66fd6ef831e4ec98957030be94189a78ca3c2986dbed57a3b97985d862c217af'
    ],
    "event_name": "TEST",
    "msg": "Waiting for an authentication response",
    "chains": [
        {
            "short_name": "",
            "required_chain_id_hex": null,
            "position": 0,
            "is_enabled": true,
            "methods": ["BLUETOOTH:1"],
            "image_name": "BLUETOOTH_1.png",
            "grace_period": null,
            "name": "Test-chain",
            "id_hex": "42b312980c8911e69140080027983191",
            "apply_for_ep_owner": false,
            "is_trusted": null
        }
    ],
    "completed_methods": [],
    "status": "MORE_DATA"
}
Body
{
  "response": {
    "address": "aabbccdd"
  },
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
    "data_id": "",
    "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
    "current_method": "BLUETOOTH:1",
    "event_data_id": "",
    "user_id": "3a76753d7f931751c79fa05d80eb058e",
    "repo_id": "42987aa00c8911e69140080027983191",
    "msgid": "AUCORE-2001",
    "plugins": [],
    "repo_obj_id": "42a3962e0c8911e69140080027983191",
    "event_name": "TEST",
    "msg": "Welcome",
    "chains": [
        {
            "short_name": "",
            "required_chain_id_hex": null,
            "position": 0,
            "is_enabled": true,
            "methods": ["BLUETOOTH:1"],
            "image_name": "BLUETOOTH_1.png",
            "grace_period": null,
            "name": "Test-chain",
            "id_hex": "42b312980c8911e69140080027983191",
            "apply_for_ep_owner": false,
            "is_trusted": null
        }
    ],
    "user_name": "LOCAL\USER1",
    "completed_methods": ["BLUETOOTH:1"],
    "status": "OK",
    "login_session_id": "Cga6cvaMTaMTaDp5TLZHPOet29O808VL"
}

BLUETOOTH:1 logon:
POST/api/v1/logon/do_logon

BLUETOOTH:1 logon steps:

  1. Send empty request to do_logon to ask server for encrypted MAC address

  2. Send mac address of enrolled device to do_logon


DEVICE_AUTH:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsStore either a public key in modulus+exponent format or a certificate in DER format
Body
{
  "response": {
    "modulus": "bd77dc79a02acda19a9ec6099cd4a........0da58c9ef04a1e2655aac84f23",
    "card_cert": null,
    "exponent": "10001"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "DEVICE_AUTH:1"
}

DEVICE_AUTH:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with a public key in modulus+exponent format or a certificate in DER format to do_enroll and check status.

Error reasons:

  • PKI_CERT_VALIDATION_FAILED
URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


DEVICE_AUTH:1 logon:

POST /api/v1/logon/kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp/do_logon
Requests1. Ask server for a challenge2. Sign the given challenge on card or token
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {}
}
Responses200
Body
{ "chains": [ { "image_name": "default",
                "is_enabled": True,
                "is_trusted": None,
                "methods": ["DEVICE_AUTH:1"],
                "name": "Test-chain",
                "position": 0,
                "short_name": ""}],
  "completed_methods": [],
  "current_method": "DEVICE_AUTH:1",
  "event_data_id": "",
  "event_name": "TEST",
  "logon_process_id": "kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
  "msg": "Waiting for an authentication signature",
  "plugins": [],
  "challenge": "f81e9d6882aca80cbe97e291ee5771aba7cc13facb3c79a5ae924e788bc4f7d2",
  "keypair_id": "6f4712e554544ac3",
  "subject": "76b3af3dd66649e896b56b51d46cfe93037a793c961ca35586c485d130375e2f",
  "reason": "PKI_WAITING_AUTH_SIGN",
  "status": "MORE_DATA"
}
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "signature": "58ad84f3a9b7244031aa55c0d....42d123bdb715a153974e992b16d022",
    "padding": "PKCS#1",
    "hash": "SHA1"
  }
}
Responses200
Body
{ "repo_obj_id": "6104a6ce424b11e5b7ebdc85de0b0889",
  "repo_id": "6104a6c5424b11e5b7ebdc85de0b0889",
  "logon_process_id": "kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
  "status": "OK",
  "plugins": [],
  "msg": "Welcome",
  "current_method": "DEVICE_AUTH:1",
  "completed_methods": ["DEVICE_AUTH:1"],
  "chains": [{ "methods": ["ANY"],
               "image_name": "default",
               "short_name": "",
               "position": 1000,
               "is_enabled": true,
               "is_trusted": null,
               "name": "TEST CHAIN"}],
  "event_data_id": "",
  "user_id": "6104a6cf424b11e5b7ebdc85de0b0889",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "DirIO8s41TbT1lm7Dh5BNfK6gRTHhXTl",
  "data_id": "",
  "event_name": "TEST"
}

DEVICE_AUTH:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

DEVICE_AUTH:1 logon steps:

  1. Ask server for a challenge by sending empty request to do_logon

  2. Sign the given challenge on card or token and send it to do_logon and check status

Error reasons:

  • PKI_WAITING_AUTH_SIGN

  • PKI_SIGN_VERIFICATION_FAILED

  • PKI_CERT_VALIDATION_FAILED

  • PKI_WRONG_CARD

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp

ID of the logon process


EMAIL_OTP:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect request
Body
{
    "login_session_id":"rBT79CAz8AWh1o920OrHumx32iaToCU9",
    "response":
        {
            "email" : "[email protected]" //(optional, if not present the email from repository will be used)
        }
}
Responses200
Body
{
  "reason": "",
  "method_id": "EMAIL_OTP:1",
  "status": "OK",
  "msg": ""
}

EMAIL_OTP:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send empty request to do_enroll and check status

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


EMAIL_OTP:1 logon:

POST /api/v1/logon/DjCTzG4tuJdwTmdWhtkbUggbertp2d6E/do_logon
Requests1. Send message to user2. Enter password from Email successfully3. Enter password from Email unsuccessfully
Body
{
  "endpoint_session_id": "caclPKkiAOkbwUMyX6kvMlIVtOdMwgvW"
}
Responses200
Body
{
  "event_name": "",
  "current_method": "EMAIL_OTP:1",
  "reason": "OTP_WAITING_PASSWORD",
  "msgid": "AUCORE-2012",
  "completed_methods": [],
  "logon_process_id": "DjCTzG4tuJdwTmdWhtkbUggbertp2d6E",
  "plugins": [],
  "status": "MORE_DATA",
  "event_data_id": "",
  "msg": "OTP password sent, please specify",
  "chains": [
    {
      "short_name": "",
      "position": 1000,
      "id_hex": null,
      "required_chain_id_hex": null,
      "is_trusted": null,
      "image_name": "ANY.png",
      "is_enabled": true,
      "methods": [
        "ANY"
      ],
      "name": "TEST CHAIN",
      "apply_for_ep_owner": false,
      "grace_period": null
    }
  ]
}
Body
{
  "endpoint_session_id": "caclPKkiAOkbwUMyX6kvMlIVtOdMwgvW",
  "response": {
    "answer": "795199"
  }
}
Responses200
Body
{
    "user_id": "470671fbf0227d268c2cc7d6b756e2c0",
    "user_name": "LDS\Admin",
    "data_id": "",
    "event_data_id": "",
    "status": "OK",
    "msgid": "AUCORE-2001",
    "completed_methods": ["EMAIL_OTP:1"],
    "msg": "Welcome",
    "repo_id": "d65f2f4e0c4e11e6b18c080027983191",
    "event_name": "",
    "user_email": "[email protected]",
    "repo_obj_id": "11a2916c4521e14e83ad19b0165311d1",
    "current_method": "EMAIL_OTP:1",
    "user_sid_hex": "0105000016ef19f498f9c6c5e52ce57b56b2314ba46e9bdd41d24e5d",
    "chains": [
        {
            "short_name": "",
            "position": 1000,
            "id_hex": null,
            "required_chain_id_hex": null,
            "is_trusted": null,
            "image_name": "ANY.png",
            "is_enabled": true,
            "methods": ["ANY"],
            "name": "TEST CHAIN",
            "apply_for_ep_owner": false,
            "grace_period": null
        }
    ],
    "user_cn": "Admin",
    "logon_process_id": "DjCTzG4tuJdwTmdWhtkbUggbertp2d6E",
    "plugins": [],
    "user_sid": "S-1-384768500-3318151576-2078616805-1261548118-3717951140-1565446721",
    "login_session_id": "VqtNECMXwMIRDLqbOFG8pBbTbG8lfSTT",
    "user_dn": "CN=Admin,CN=test"
}
Body
{
  "endpoint_session_id": "caclPKkiAOkbwUMyX6kvMlIVtOdMwgvW",
  "response": {
    "answer": "795191"
  }
}
Responses200
Body
{
  "msg": "Incorrect answer. Please try again",
  "reason": "OTP_WRONG_PASSWORD",
  "current_method": "EMAIL_OTP:1",
  "plugins": [],
  "status": "MORE_DATA",
  "chains": [
    {
      "short_name": "",
      "id_hex": null,
      "is_enabled": true,
      "position": 1000,
      "image_name": "ANY.png",
      "methods": [
        "ANY"
      ],
      "required_chain_id_hex": null,
      "name": "TEST CHAIN",
      "grace_period": null,
      "apply_for_ep_owner": false,
      "is_trusted": null
    }
  ],
  "event_data_id": "",
  "event_name": "",
  "logon_process_id": "DjCTzG4tuJdwTmdWhtkbUggbertp2d6E",
  "msgid": "AUCORE-2015",
  "completed_methods": []
}

EMAIL_OTP:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

EMAIL_OTP:1 logon steps:

  1. Send empty request to do_logon to send email

  2. Send request with password from received email to do_logon and check status

Error reasons:

  • OTP_CANNOT_SEND

  • OTP_TOO_MANY_SENT

  • OTP_WAITING_PASSWORD

  • OTP_NO_PASSWORD

  • OTP_PASSWORD_EXPIRED

  • OTP_WRONG_PASSWORD

  • OTP_NO_EXPLICIT_RECIPIENT

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: DjCTzG4tuJdwTmdWhtkbUggbertp2d6E

ID of the logon process


EMAIL_OTP:1 method call:

POST /api/v1/logon_method/EMAIL_OTP:1
RequestsCorrect request
Body
{
    "endpoint_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9", (trusted endpoint required)
    "email": "[email protected]"
}
Responses200
Body
{
  "otp": "123456"
}

EMAIL_OTP:1 method call:
POST/api/v1/logon_method/EMAIL_OTP:1

EMAIL_OTP:1 method steps:

  1. Send recipient email in request and check OTP

EMERG_PASSWORD:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect request
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "password": "emerg_password"
  }
}
Responses200
Body
{
  "reason": "",
  "method_id": "EMERG_PASSWORD:1",
  "status": "OK",
  "msg": ""
}

EMERG_PASSWORD:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with password to do_enroll and check status.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


EMERG_PASSWORD:1 logon:

POST /api/v1/logon/TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS/do_logon
RequestsEmergency password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "my-emergency-password"
  }
}
Responses200
Body
{
  "user_id": "4f34e2882991440ddd0fd515e0d0236c",
  "completed_methods": [
    "EMERG_PASSWORD:1"
  ],
  "repo_id": "3c9c1fd8061e11e6b224080027983191",
  "status": "OK",
  "repo_obj_id": "3caa08a0061e11e6b224080027983191",
  "event_data_id": "",
  "logon_process_id": "jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "TmPxkC98vF4FGhDvqedjXItbmGjVJYTD",
  "plugins": [],
  "event_name": "",
  "chains": [
    {
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "ANY"
      ],
      "short_name": "",
      "image_name": "ANY.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "current_method": "EMERG_PASSWORD:1",
  "msgid": "AUCORE-2001",
  "msg": "Welcome",
  "data_id": ""
}

EMERG_PASSWORD:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

EMERG_PASSWORD:1 logon steps:

  1. Send password to do_logon and check status

Error reasons:

  • EMERG_PASSWORD_EXPIRED

  • EMERG_PASSWORD_INEFFECTIVE

  • EMERG_PASSWORD_EXHAUSTED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS

ID of the logon process


FACE:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
Requestsface enroll with image
Body
{
    "response": {"face_img": <Image content>},
    "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "FACE:1"
}

FACE:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request to do_enroll with face image

Fields description: face_img: It should be urlencoded of base64 string of face image

Image allowed formats : PNG, JPEG, GIF

Error reasons:

  • INVALID_FACE_IMAGE

  • MISSING_PARAMETERS

  • IMAGE_SIZE_LIMIT_EXCEEDED

  • ENROLLMENT_FAILED

  • IMAGE_NOT_FOUND

UI uses Device Service by calling this url: wss://127.0.0.1:8441/api/v1/video through websocket It should return json with captured face image. Device Service returns captured image in png format.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

(required, string) - ID of the enroll process


FACE:1 logon:

POST /api/v1/logon/kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp/do_logon
Requestsface capture
Body
{   "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
    "response": {"face_img": <Image content>}
}
Responses200
Body
{
    "event_data_id": "",
    "msgid": "AUCORE-2001",
    "logon_process_id": "kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
    "login_session_id": "iCFCUvGVK9zlDQtWa018UWKUwuNHEYcn",
    "current_method": "FACE:1",
    "chains": [
        {
          "position": 1000,
          "short_name": "",
          "grace_period": null,
          "methods": [
            "FACE:1"
          ],
          "is_enabled": true,
          "name": "TEST CHAIN",
          "id_hex": null,
          "required_chain_id_hex": null,
          "is_trusted": null,
          "apply_for_ep_owner": false,
          "image_name": "FACE_1.png"
        }
    ],
    "repo_obj_id": "c0fd1ab20b0e11e6b224080027983191",
    "plugins": [],
    "msg": "Welcome",
    "status": "OK",
    "user_id": "84a0a279d391de4b2fd70ea38b46d3ce",
    "data_id": "",
    "event_name": "",
    "repo_id": "c0eeb0ee0b0e11e6b224080027983191",
    "completed_methods": [
        "FACE:1"
    ],
    "user_name": "LOCAL\ADMIN"

}

FACE:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

FACE:1 logon steps:

  1. Send request to do_logon with face image

Fields description: face_img: It should be urlencoded of base64 string of face image

Image allowed formats : PNG, JPEG, GIF

Error reasons:

  • FACE_MISMATCH

  • LOGON_FAILED

UI uses Device Service by calling this url: wss://127.0.0.1:8441/api/v1/video through websocket It should return json with captured face image. Device Service returns captured image in png format.

URI Parameters
HideShow
logon_process_id
string (required) Example: kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp

(required, 32 symbol id) - ID of the logon process


FIDO2:1 enroll:

POST /api/v1/enroll/uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc/do_enroll
RequestsdoEnroll: Start enrolldoEnroll: Check status
Body
{
    "login_session_id": "CD506E53Mts35Qp2YI3gCWPgtjx6Kt4M",
    "response": {
        "rp_id": "localhost"       // REQUIRED: It should be hostname/ domain name of the requested url.
    }
}
Responses200
Body
For the first call:
{
    "status": "MORE_DATA",
    "msg": "Waiting for Web Authentication data",
    "reason": "WAITING_WEBAUTH_RESPONSE",
    "method_id": "FIDO2:1",
}
Body
{
  "login_session_id": "CD506E53Mts35Qp2YI3gCWPgtjx6Kt4M"
}
Responses200
Body
For the next calls until the user will be verified by the WebAuthn (FIDO2):
{
    "status": "MORE_DATA",
    "msg": "Waiting for Authentication data",
    "reason": "WAITING_WEBAUTH_RESPONSE",
    "method_id": "FIDO2:1",
}

The final result when the user passed through WebAuthn (FIDO2) successfully:
{
    "status": "OK",
    "msg": "",
    "reason": "",
    "method_id": "FIDO2:1"
}

The final result when the user failed WebAuthn (FIDO2) verification:
{
    "status": "FAILED",
    "msg": "",
    "reason": "FIDO2_FAILED",
    "method_id": "FIDO2:1"
}

FIDO2:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request to do_enroll and check status.

Error reasons:

  • WAITING_WEBAUTH_RESPONSE

  • WRONG_CHALLENGE

  • INVALID_CREDENTIAL_ID

  • WRONG_SIGNATURE

  • FIDO2_FAILED

URI Parameters
HideShow
enroll_process_id
string (required) Example: uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc

ID of the enroll process


FIDO2:1 logon:

POST /api/v1/logon/qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz/do_logon
RequestsdoLogon: Start logondoLogon: Check result
Body
{
  "endpoint_session_id": "qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz",
  "method_id": "FIDO2:1",
  "response": {}
}
Responses200
Body
For the first call:
{
    "event_data_id": "AUTHENTICATORS MANAGEMENT",
    "msgid": "AUCORE-3057",
    "category_id": "",
    "reason": "WAITING_WEBAUTH_RESPONSE",
    "msg": "Waiting for Authentication data",
    "linked_logon": false,
    "plugins": [ ],
    "event_name": "Authenticators Management",
    "status": "MORE_DATA",
    "chains": [
        {
            "tenant_id": "def0def0def0def0def0def0def0def0",
            "is_enabled": true,
            "image_name": "FIDO2_1.png",
            "name": "fido2",
            "id_hex": "b8476540b49411e7b93e000c294d5acc",
            "is_trusted": null,
            "apply_for_ep_owner": false,
            "short_name": "fido2",
            "position": 0,
            "methods": ["FIDO2:1"],
            "mfa_tags": [ ],
            "required_chain_id_hex": null,
            "grace_period": null
        }
    ],
    "completed_methods": [ ],
    "method_id": "FIDO2:1",
    "current_method": "FIDO2:1",
    "logon_process_id": "qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz"
}
Body
{
  "endpoint_session_id": "qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz",
  "method_id": "FIDO2:1"
}
Responses200
Body
The final result when the user passed through WebAuthn (FIDO2) successfully:
{
    "status": "OK",
    "msg": "Welcome!",
    "linked_logon": false,
    "plugins": [],
    "login_session_id": "Fdsoxy7pvH5AijDRxFdgfkgNuECghmGh",
    "completed_chain": {
        "id_hex": null,
        "tenant_id": "def0def0def0def0def0def0def0def0",
        "is_trusted": null,
        "is_enabled": true,
        "name": "TEST CHAIN",
        "short_name": "",
        "methods": [
            "ANY"
        ],
        "position": 1000,
        "apply_for_ep_owner": false,
        "image_name": "ANY.png",
        "required_chain_id_hex": null,
        "grace_period": null,
        "mfa_tags": []
    },
    "user_id": "6c5f9a6863d233ab6310602a8faee7f1",
    "user_name": "LOCAL\ADMIN",
    "repo_id": "2e0598aa5cf711e8bb2a0242ac130002",
    "repo_obj_id": "2e06ede05cf711e8bb2a0242ac130002",
    "msgid": "AUCORE-2001",
    "chains": [
        {
            "id_hex": null,
            "tenant_id": "def0def0def0def0def0def0def0def0",
            "is_trusted": null,
            "is_enabled": true,
            "name": "TEST CHAIN",
            "short_name": "",
            "methods": [
                "ANY"
            ],
            "position": 1000,
            "apply_for_ep_owner": false,
            "image_name": "ANY.png",
            "required_chain_id_hex": null,
            "grace_period": null,
            "mfa_tags": []
        }
    ],
    "current_method": "FIDO2:1",
    "completed_methods": [
        "FIDO2:1"
    ],
    "logon_process_id": "eurdv8XtHCYrUM6YgPkIQm3WMuF1Kwnb",
    "event_name": "",
    "event_type": "Generic",
    "event_data_id": "",
    "data_id": "",
    "category_id": ""
}

The final result when error:
{
    "status": "FAILED",
    "msg": "FIDO2 verification failed",
    "linked_logon": false,
    "reason": "FIDO2_FAILED",
    "plugins": [],
    "msgid": "AUCORE-3058",
    "chains": [
        {
            "id_hex": null,
            "tenant_id": "def0def0def0def0def0def0def0def0",
            "is_trusted": null,
            "is_enabled": true,
            "name": "TEST CHAIN",
            "short_name": "",
            "methods": [
                "ANY"
            ],
            "position": 1000,
            "apply_for_ep_owner": false,
            "image_name": "ANY.png",
            "required_chain_id_hex": null,
            "grace_period": null,
            "mfa_tags": []
        }
    ],
    "current_method": "FIDO2:1",
    "completed_methods": [],
    "logon_process_id": "XqxaOgvchUZB1vdWAMxQ3opIzMhpZaFA",
    "event_name": "",
    "event_type": "Generic",
    "event_data_id": "",
    "data_id": "",
    "category_id": ""
}

FIDO2:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

FIDO2:1 logon steps:

  1. Send request to do_logon and check status.

Error reasons:

  • WAITING_WEBAUTH_RESPONSE

  • WRONG_CHALLENGE

  • INVALID_CREDENTIAL_ID

  • WRONG_SIGNATURE

  • FIDO2_FAILED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz

ID of the logon process


FINGER:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsMultiple finger enroll with imagesMultiple finger enroll with iso templatesPartial enrollment: Add operationPartial enrollment: Remove operationPartial enrollment: End operation
Body
{
  "response": {
    "captures": [
      {
        "Finger": "1",
        "Image": {
          "BitsPerPixel": 8,
          "BytesPerLine": 300,
          "Dpi": 500,
          "Height": 300,
          "Width": 300,
          "captureStatus": "Ok",
          "Image": "<image content>"
        }
      },
      {
        "Finger": "1",
        "Image": {
          "BitsPerPixel": 8,
          "BytesPerLine": 300,
          "Dpi": 500,
          "Height": 300,
          "Width": 300,
          "captureStatus": "Ok",
          "Image": "<image content>"
        }
      }
    ],
    "duress_finger_index": "1"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "FINGER:1"
}
Body
{
  "response": {
    "captures": [
      {
        "Finger": "1",
        "Image": {
          "ISO": "<iso finger capture template>",
          "captureStatus": "OK"
        }
      },
      {
        "Finger": "1",
        "Image": {
          "ISO": "<iso finger capture template>",
          "captureStatus": "OK"
        }
      }
    ],
    "duress_finger_index": "1"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "FINGER:1"
}
Body
{
  "response": {
    "captures": [
      {
        "Finger": "1",
        "Image": {
          "BitsPerPixel": 8,
          "BytesPerLine": 300,
          "Dpi": 500,
          "Height": 300,
          "Width": 300,
          "captureStatus": "Ok",
          "Image": "<image content>"
        }
      },
      {
        "Finger": "1",
        "Image": {
          "BitsPerPixel": 8,
          "BytesPerLine": 300,
          "Dpi": 500,
          "Height": 300,
          "Width": 300,
          "captureStatus": "Ok",
          "Image": "<image content>"
        }
      }
    ],
    "operation": "add"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H",
  "auth_t_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "reason": "FINGER_METHOD_WAITS_NEXT_OPERATION",
  "msg": "Waiting for next operation",
  "status": "MORE_DATA",
  "method_id": "FINGER:1"
}
Body
{
  "response": {
    "fingers": [
      "1",
      "2"
    ],
    "operation": "remove"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H",
  "auth_t_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "reason": "FINGER_METHOD_WAITS_NEXT_OPERATION",
  "msg": "Waiting for next operation",
  "status": "MORE_DATA",
  "method_id": "FINGER:1"
}
Body
{
  "response": {
    "operation": "end"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "FINGER:1"
}

FINGER:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request to do_enroll with finger images

Fields description: Finger: “1” , where “1” is finger id from ids below

Finger ids:

  • ANY_FINGER = “0”

  • RIGHT_THUMB = “1”

  • LEFT_THUMB = “2”

  • RIGHT_INDEX = “3”

  • LEFT_INDEX = “4”

  • RIGHT_MIDDLE = “5”

  • LEFT_MIDDLE = “6”

  • RIGHT_RING = “7”

  • LEFT_RING = “8”

  • RIGHT_LITTLE = “9”

  • LEFT_LITTLE = “10”

Image content format:

  • BitsPerPixel, integer, bits per pixel, support only 8 bits now

  • BytesPerLine, integer, count of bytes per one row

  • Width , integer, length of row in pixels

  • Height, integer, pixel row’s count

  • Dpi, integer, is not used now

  • Image, string, base64 encoded string with bytes

  • captureStatus, string, result of capturing

Template content format:

  • ISO: string, base64 encoded string with iso content

  • captureStatus, string, result of capturing

duress_finger_index: “1”, where 1 is the finger id

Partial enrollment

To add / remove fingers to an existing template:

  1. Send request to do_enroll with finger images

Fields description: - auth_t_id: “IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H”, (required, string), ID of template - operation: “add”, (required, string), one of (add, remove, end)

Error reasons:

  • INCORRECT_FINGERS_COUNT

  • INCORRECT_CAPTURES_COUNT_PER_FINGER

  • FINGER_METHOD_WAITS_NEXT_OPERATION

UI uses Device Service by calling this url: https://127.0.0.1:8442/api/v1/fingerprint/capture It should return json with captured fingerprint. Device Service returns capture in ISO or image format. Type of response is depended on sensor type. So if device service returns ISO send ISO as response or image if device service returns image.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


FINGER:1 logon:

POST /api/v1/logon/kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp/do_logon
RequestsSend finger captureSend finger capture's iso template
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "capture": {
      "BitsPerPixel": 8,
      "BytesPerLine": 300,
      "Dpi": 500,
      "Height": 300,
      "Width": 300,
      "captureStatus": "Ok",
      "Image": "<image content>"
    }
  }
}
Responses200
Body
{
    "event_data_id": "",
    "msgid": "AUCORE-2001",
    "logon_process_id": "kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
    "login_session_id": "iCFCUvGVK9zlDQtWa018UWKUwuNHEYcn",
    "current_method": "FINGER:1",
    "chains": [
        {
          "position": 1000,
          "short_name": "",
          "grace_period": null,
          "methods": [
            "FINGER:1"
          ],
          "is_enabled": true,
          "name": "TEST CHAIN",
          "id_hex": null,
          "required_chain_id_hex": null,
          "is_trusted": null,
          "apply_for_ep_owner": false,
          "image_name": "FINGER_1.png"
        }
    ],
    "repo_obj_id": "c0fd1ab20b0e11e6b224080027983191",
    "plugins": [],
    "msg": "Welcome",
    "status": "OK",
    "user_id": "84a0a279d391de4b2fd70ea38b46d3ce",
    "data_id": "",
    "event_name": "",
    "repo_id": "c0eeb0ee0b0e11e6b224080027983191",
    "completed_methods": [
        "FINGER:1"
    ],
    "user_name": "LOCAL\ADMIN"
}
Headers
Content-Type: application/json
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "capture": {
      "ISO": "<finger capture's iso template>",
      "captureStatus": "OK"
    }
  }
}
Responses200
Body
{
    "event_data_id": "",
    "msgid": "AUCORE-2001",
    "logon_process_id": "kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
    "login_session_id": "iCFCUvGVK9zlDQtWa018UWKUwuNHEYcn",
    "current_method": "FINGER:1",
    "chains": [
        {
          "position": 1000,
          "short_name": "",
          "grace_period": null,
          "methods": [
            "FINGER:1"
          ],
          "is_enabled": true,
          "name": "TEST CHAIN",
          "id_hex": null,
          "required_chain_id_hex": null,
          "is_trusted": null,
          "apply_for_ep_owner": false,
          "image_name": "FINGER_1.png"
        }
    ],
    "repo_obj_id": "c0fd1ab20b0e11e6b224080027983191",
    "plugins": [],
    "msg": "Welcome",
    "status": "OK",
    "user_id": "84a0a279d391de4b2fd70ea38b46d3ce",
    "data_id": "",
    "event_name": "",
    "repo_id": "c0eeb0ee0b0e11e6b224080027983191",
    "completed_methods": [
        "FINGER:1"
    ],
    "user_name": "LOCAL\ADMIN"
}

FINGER:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

FINGER:1 logon steps:

  1. Send to server finger capture or finger capture’s iso template

Image content format:

  • BitsPerPixel, integer, bits per pixel, support only 8 bits now

  • BytesPerLine, integer, count of bytes per one row

  • Width , integer, length of row in pixels

  • Height, integer, pixel row’s count

  • Dpi, integer, is not used now

  • Image, string, base64 encoded string with bytes

  • captureStatus, string, result of capturing

Template content format:

  • ISO: string, base64 encoded string with iso content

  • captureStatus, string, result of capturing

Error reasons:

  • 400

UI uses Device Service by calling this url: https://127.0.0.1:8442/api/v1/fingerprint/capture It should return json with captured fingerprint. Device Service returns capture in ISO or image format. Type of response is depended on sensor type. So if device service returns ISO send ISO as response or image if device service returns image.

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp

ID of the logon process


FLEX_OTP:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsFLEX_OTP:1 enroll
Body
{
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "reason": "",
  "method_id": "FLEX_OTP:1",
  "status": "OK",
  "msg": ""
}

FLEX_OTP:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send empty request to do_enroll and check status.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


FLEX_OTP:1 logon:

POST /api/v1/logon/f0fzSCkoGcCFMJTDRalx5nnsC9zEYHBQ/do_logon
RequestsSimple FLEX OTP password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "123456"
  }
}
Responses200
Body
{
    "event_data_id": "",
    "msgid": "AUCORE-2001",
    "logon_process_id": "f0fzSCkoGcCFMJTDRalx5nnsC9zEYHBQ",
    "login_session_id": "9QHUl8xbBNo4PUO6UXYzbHltNaMmNpSL",
    "current_method": "FLEX_OTP:1",
    "chains": [
    {
      "position": 1000,
      "short_name": "",
      "grace_period": null,
      "methods": [
        "ANY"
      ],
      "is_enabled": true,
      "name": "TEST CHAIN",
      "id_hex": null,
      "required_chain_id_hex": null,
      "is_trusted": null,
      "apply_for_ep_owner": false,
      "image_name": "ANY.png"
    }
    ],
    "repo_obj_id": "c0fd1ab20b0e11e6b224080027983191",
    "plugins": [],
    "msg": "Welcome",
    "status": "OK",
    "user_id": "84a0a279d391de4b2fd70ea38b46d3ce",
    "data_id": "",
    "event_name": "",
    "repo_id": "c0eeb0ee0b0e11e6b224080027983191",
    "completed_methods": [
    "FLEX_OTP:1"
    ],
    "user_name": "LOCAL\ADMIN"
}

FLEX_OTP:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

FLEX_OTP:1 logon steps:

  1. Send otp-password to do_logon and check status

Error reasons:

  • FLEX_OTP_WRONG_OTP
URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: f0fzSCkoGcCFMJTDRalx5nnsC9zEYHBQ

ID of the logon process


HOTP:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect request with secret and counterCorrect request with 3 hotps
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "secret": "0000000000000100",
    "counter": 10
  }
}
Responses200
Body
{
  "reason": "",
  "method_id": "HOTP:1",
  "status": "OK",
  "msg": ""
}
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "serial": "987654321",
    "hotp1": "472265",
    "hotp2": "194708",
    "hotp3": "468067"
  }
}
Responses200
Body
{
  "reason": "",
  "method_id": "HOTP:1",
  "status": "OK",
  "msg": ""
}

HOTP:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with token serial (or secret) and 3 hotps (or counter) to do_enroll and check status.

Remember user device (smartphone etc.) HOTP secret and algoritm parameters

HOTP auth_template is shared secret and starting counter

Request fields:

  • serial, string, optional

  • secret, hex string, optional, either serial or secret must be specified

  • hotp1, hotp2, hotp3, consecutive otp password, optional

  • counter, integer, optional, either counter or 3 hotps must be specified

  • hash, optional, one of hashlib.algorithms_guaranteed

  • token_public_id, optional, Yubikey tokens can be configured to insert their public ID before OTP

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


HOTP:1 logon:

POST /api/v1/logon/fae8kchtfY2p2t3W0OWrCS3UHu3nf6eM/do_logon
RequestsSimple HOTP password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "123456"
  }
}
Responses200
Body
{
    "event_data_id": "",
    "msgid": "AUCORE-2001",
    "logon_process_id": "fae8kchtfY2p2t3W0OWrCS3UHu3nf6eM",
    "login_session_id": "iCFCUvGVK9zlDQtWa018UWKUwuNHEYcn",
    "current_method": "HOTP:1",
    "chains": [
    {
      "position": 1000,
      "short_name": "",
      "grace_period": null,
      "methods": [
        "ANY"
      ],
      "is_enabled": true,
      "name": "TEST CHAIN",
      "id_hex": null,
      "required_chain_id_hex": null,
      "is_trusted": null,
      "apply_for_ep_owner": false,
      "image_name": "ANY.png"
    }
    ],
    "repo_obj_id": "c0fd1ab20b0e11e6b224080027983191",
    "plugins": [],
    "msg": "Welcome",
    "status": "OK",
    "user_id": "84a0a279d391de4b2fd70ea38b46d3ce",
    "data_id": "",
    "event_name": "",
    "repo_id": "c0eeb0ee0b0e11e6b224080027983191",
    "completed_methods": [
    "HOTP:1"
    ],
    "user_name": "LOCAL\ADMIN"
    }

HOTP:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

HOTP:1 logon steps:

  1. Send otp-password to do_logon and check status

Error reasons:

  • HOTP_PASSWORD_WRONG

  • HOTP_PASSWORD_UNDEFINED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: fae8kchtfY2p2t3W0OWrCS3UHu3nf6eM

ID of the logon process


LDAP_PASSWORD:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsLDAP_PASSWORD:1 enroll
Body
{
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "reason": "",
  "method_id": "LDAP_PASSWORD:1",
  "status": "OK",
  "msg": ""
}

LDAP_PASSWORD:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send empty request to do_enroll and check status.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


LDAP_PASSWORD:1 logon:

POST /api/v1/logon/jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9/do_logon
RequestsSimple ldap password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "my-ldap-password"
  }
}
Responses200
Body
{
  "user_id": "4f34e2882991440ddd0fd515e0d0236c",
  "completed_methods": [
    "LDAP_PASSWORD:1"
  ],
  "repo_id": "3c9c1fd8061e11e6b224080027983191",
  "status": "OK",
  "repo_obj_id": "3caa08a0061e11e6b224080027983191",
  "event_data_id": "",
  "logon_process_id": "jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "TmPxkC98vF4FGhDvqedjXItbmGjVJYTD",
  "plugins": [],
  "event_name": "",
  "chains": [
    {
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "ANY"
      ],
      "short_name": "",
      "image_name": "ANY.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "current_method": "LDAP_PASSWORD:1",
  "msgid": "AUCORE-2001",
  "msg": "Welcome",
  "data_id": ""
}

LDAP_PASSWORD:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

LDAP_PASSWORD:1 logon steps:

  1. Send password to do_logon and check status

Error reasons:

  • LDAP_PASSWORD_UNDEFINED

  • LDAP_PASSWORD_WRONG

  • LDAP_PASSWORD_ACCOUNT_RESTRICTION

  • LDAP_PASSWORD_INVALID_LOGON_HOURS

  • LDAP_PASSWORD_INVALID_WORKSTATION

  • LDAP_PASSWORD_ACCOUNT_DISABLED

  • LDAP_PASSWORD_TOO_MANY_CONTEXT_IDS

  • LDAP_PASSWORD_ACCOUNT_EXPIRED

  • LDAP_PASSWORD_MUST_CHANGE

  • LDAP_PASSWORD_ACCOUNT_LOCKED_OUT

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9

ID of the logon process


OAUTH2:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsOAUTH2:1 enroll
Body
{
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "reason": "",
  "method_id": "OAUTH2:1",
  "status": "OK",
  "msg": ""
}

OAUTH2:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send empty request to do_enroll and check status.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


OAUTH2:1 logon:

POST /api/v1/logon/TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS/do_logon
RequestsOAuth2 access token doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "access_token": "access_token_value"
  }
}
Responses200
Body
{
  "user_id": "4f34e2882991440ddd0fd515e0d0236c",
  "completed_methods": [
    "OAUTH2:1"
  ],
  "repo_id": "3c9c1fd8061e11e6b224080027983191",
  "status": "OK",
  "repo_obj_id": "3caa08a0061e11e6b224080027983191",
  "event_data_id": "",
  "logon_process_id": "jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "TmPxkC98vF4FGhDvqedjXItbmGjVJYTD",
  "plugins": [],
  "event_name": "",
  "chains": [
    {
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "ANY"
      ],
      "short_name": "",
      "image_name": "ANY.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "current_method": "OAUTH2:1",
  "msgid": "AUCORE-2001",
  "msg": "Welcome",
  "data_id": ""
}

OAUTH2:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

OAUTH2:1 logon steps:

  1. Send access token to do_logon and check status

Error reasons:

  • OAUTH2_WRONG_TOKEN

  • INACTIVE_TOKEN

  • WRONG_USER

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS

ID of the logon process


PKI:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsStore either a public key in modulus+exponent format or a certificate in DER format
Body
{
  "response": {
    "card_uid": "1",
    "modulus": "bd77dc79a02acda19a9ec6099cd4a........0da58c9ef04a1e2655aac84f23",
    "card_cert": null,
    "exponent": "10001"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "PKI:1"
}

PKI:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with a public key in modulus+exponent format or a certificate in DER format to do_enroll and check status.

Error reasons:

  • PKI_CERT_VALIDATION_FAILED
URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


PKI:1 logon:

POST /api/v1/logon/kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp/do_logon
Requests1. Ask server for a challenge2. Sign the given challenge on card or token
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {}
}
Responses200
Body
{ "chains": [ { "image_name": "default",
                "is_enabled": True,
                "is_trusted": None,
                "methods": ["PKI:1"],
                "name": "Test-chain",
                "position": 0,
                "short_name": ""}],
  "completed_methods": [],
  "current_method": "PKI:1",
  "event_data_id": "",
  "event_name": "TEST",
  "logon_process_id": "kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
  "msg": "Waiting for an authentication signature",
  "plugins": [],
  "challenge": "f81e9d6882aca80cbe97e291ee5771aba7cc13facb3c79a5ae924e788bc4f7d2",
  "keypair_id": "6f4712e554544ac3",
  "subject": "76b3af3dd66649e896b56b51d46cfe93037a793c961ca35586c485d130375e2f",
  "reason": "PKI_WAITING_AUTH_SIGN",
  "status": "MORE_DATA"
}
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "signature": "58ad84f3a9b7244031aa55c0d....42d123bdb715a153974e992b16d022",
    "padding": "PKCS#1",
    "hash": "SHA1"
  }
}
Responses200
Body
{ "repo_obj_id": "6104a6ce424b11e5b7ebdc85de0b0889",
  "repo_id": "6104a6c5424b11e5b7ebdc85de0b0889",
  "logon_process_id": "kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp",
  "status": "OK",
  "plugins": [],
  "msg": "Welcome",
  "current_method": "PKI:1",
  "completed_methods": ["PKI:1"],
  "chains": [{ "methods": ["ANY"],
               "image_name": "default",
               "short_name": "",
               "position": 1000,
               "is_enabled": true,
               "is_trusted": null,
               "name": "TEST CHAIN"}],
  "event_data_id": "",
  "user_id": "6104a6cf424b11e5b7ebdc85de0b0889",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "DirIO8s41TbT1lm7Dh5BNfK6gRTHhXTl",
  "data_id": "",
  "event_name": "TEST"
}

PKI:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

PKI:1 logon steps:

  1. Ask server for a challenge by sending empty request to do_logon

  2. Sign the given challenge on card or token and send it to do_logon and check status

Error reasons:

  • PKI_WAITING_AUTH_SIGN

  • PKI_SIGN_VERIFICATION_FAILED

  • PKI_CERT_VALIDATION_FAILED

  • PKI_WRONG_CARD

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: kytfmodEy4QmcMKgEb9cuGpLpNv9ooYp

ID of the logon process


RADIUS:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsRADIUS enroll
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9"
}
Responses200
Body
{
  "reason": "",
  "method_id": "RADIUS:1",
  "status": "OK",
  "msg": ""
}

RADIUS:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with fields below to do_enroll and check status.

Request fields:

  • user_name (optional) - send to RADIUS instead of user.user_name

  • send_reponame (optional) - send ‘repository_name\peter’, not just ‘peter’

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


RADIUS:1 logon:

POST /api/v1/logon/TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS/do_logon
RequestsRADIUS password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "my-radius-password"
  }
}
Responses200200
Body
{
  "user_id": "4f34e2882991440ddd0fd515e0d0236c",
  "completed_methods": [
    "RADIUS:1"
  ],
  "repo_id": "3c9c1fd8061e11e6b224080027983191",
  "status": "OK",
  "repo_obj_id": "3caa08a0061e11e6b224080027983191",
  "event_data_id": "",
  "logon_process_id": "jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "TmPxkC98vF4FGhDvqedjXItbmGjVJYTD",
  "plugins": [],
  "event_name": "",
  "chains": [
    {
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "ANY"
      ],
      "short_name": "",
      "image_name": "ANY.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "current_method": "RADIUS:1",
  "msgid": "AUCORE-2001",
  "msg": "Welcome",
  "data_id": ""
}
Body
{
    "reply_message": "Your password was expired. Please enter new password"
    "chains": [
        {
            "id_hex": null,
            "is_enabled": true,
            "short_name": "",
            "grace_period": null,
            "image_name": "ANY.png",
            "is_trusted": null,
            "name": "TEST CHAIN",
            "methods": ["ANY"],
            "apply_for_ep_owner": false,
            "position": 1000,
            "required_chain_id_hex": null
        }
    ],
    "current_method": "RADIUS:1",
    "status": "MORE_DATA",
    "logon_process_id": "6MwzQQ2AKGtTW0q0q2VEQ3tIs0Y6Py0n",
    "event_name": "",
    "completed_methods": [],
    "event_data_id": "",
    "plugins": [],
    "method_id": "RADIUS:1"
}

RADIUS:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

RADIUS:1 logon steps:

  1. Send password to do_logon and check status

Error reasons:

  • RADIUS_WRONG_PASSWORD
URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS

ID of the logon process


SECQUEST:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
Requests1. Get questions2. Send answers
Body
{
  "login_session_id": "ySHjXQyPAH1dIXYeq3arbMQd7wyP3mMm"
}
Responses200
Body
{
  "msgid": "AUCORE-2046",
  "method_id": "SECQUEST:1",
  "reason": "SECQUEST_WAITING_ANSWERS",
  "status": "MORE_DATA",
  "msg": "Waiting for the answers...",
  "questions": {
    "0": "question #0",
    "1": "question #1",
    "2": "question #2",
    "3": "question #3",
    "4": "question #4",
    "5": "question #5",
    "6": "question #6",
    "7": "question #7",
    "8": "question #8",
    "9": "question #9"
  }
}
Body
{
  "response": {
    "answers": {
      "0": "answer #0",
      "1": "answer #1",
      "2": "answer #2",
      "3": "answer #3",
      "4": "answer #4",
      "5": "answer #5",
      "6": "answer #6",
      "7": "answer #7",
      "8": "answer #8",
      "9": "answer #9"
    }
  },
  "login_session_id": "ySHjXQyPAH1dIXYeq3arbMQd7wyP3mMm"
}
Responses200
Body
{
  "msg": "",
  "method_id": "SECQUEST:1",
  "reason": "",
  "status": "OK"
}

SECQUEST:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

SECQUEST:1 enroll steps:

  1. Send empty request to do_enroll to receive questions

  2. Send answers to do_enroll and check status.

Error reasons:

  • SECQUEST_WAITING_ANSWERS
URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


SECQUEST:1 logon:

POST /api/v1/logon/2rMurbLwdVVmL4MZYnaJQdh1RWV7ekDx/do_logon
Requests1. Get questions from service2. Send answers
Body
{
  "endpoint_session_id": "peSWzJrCY3BH10TaP6nRrZiQy8ahauIt"
}
Responses200
Body
{
  "status": "MORE_DATA",
  "plugins": [],
  "event_name": "",
  "chains": [
    {
      "apply_for_ep_owner": false,
      "is_trusted": null,
      "image_name": "ANY.png",
      "short_name": "",
      "id_hex": null,
      "position": 1000,
      "grace_period": null,
      "is_enabled": true,
      "methods": [
        "ANY"
      ],
      "required_chain_id_hex": null,
      "name": "TEST CHAIN"
    }
  ],
  "reason": "SECQUEST_WAITING_ANSWERS",
  "method_id": "SECQUEST:1",
  "questions": {
    "1": "question #1",
    "2": "question #2",
    "3": "question #3",
    "4": "question #4",
    "7": "question #7"
  },
  "msg": "Waiting for the answers...",
  "event_data_id": "",
  "msgid": "AUCORE-2046",
  "completed_methods": [],
  "logon_process_id": "2rMurbLwdVVmL4MZYnaJQdh1RWV7ekDx",
  "current_method": "SECQUEST:1"
}
Body
{
  "response": {
    "answers": {
      "1": "answer #1",
      "2": "answer #2",
      "3": "answer #3",
      "4": "answer #4",
      "7": "answer #7"
    }
  },
  "endpoint_session_id": "peSWzJrCY3BH10TaP6nRrZiQy8ahauIt"
}
Responses200
Body
{
    "user_name": "LOCAL\ADMIN",
    "plugins": [],
    "logon_process_id": "2rMurbLwdVVmL4MZYnaJQdh1RWV7ekDx",
    "user_id": "bdb2b894ce176333bf70a35f1f961126",
    "msgid": "AUCORE-2001",
    "repo_obj_id": "46dfef2c0c7411e687c1080027983191",
    "status": "OK",
    "event_data_id": "",
    "event_name": "",
    "msg": "Welcome",
    "current_method": "SECQUEST:1",
    "chains": [
        {
            "apply_for_ep_owner": false,
            "is_trusted": null,
            "image_name": "ANY.png",
            "short_name": "",
            "id_hex": null,
            "position": 1000,
            "grace_period": null,
            "is_enabled": true,
            "methods": ["ANY"],
            "required_chain_id_hex": null,
            "name": "TEST CHAIN"
        }
    ],
    "login_session_id": "doB7cTIWcAaE5tAIar6VnPPnKKf5wHdN",
    "repo_id": "46dac56a0c7411e687c1080027983191",
    "data_id": "",
    "completed_methods": ["SECQUEST:1"]
}

SECQUEST:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

SECQUEST:1 logon steps:

  1. Send empty request to do_logon to receive questions

  2. Send answers to do_logon and check status

Error reasons:

  • SECQUEST_WRONG_ANSWERS

  • SECQUEST_WAITING_ANSWERS

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: 2rMurbLwdVVmL4MZYnaJQdh1RWV7ekDx

ID of the logon process


CARD:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsSmartcard enroll
Body
{
  "response": {
    "card_cert": "308205243082040ca00302010202100e62f26..................a5883aa073b4588",
    "card_uid": "0e62f260aa610be177ba6c5d052ef002"
  },
  "login_session_id": "KOYxcRUuuZxDsEhxiycof4XwcuI2lbwk"
}
Responses200
Body
{
  "method_id": "CARD:1",
  "status": "OK",
  "reason": "",
  "msg": "Enrollment is complete",
  "msgid": "AUCORE-3001"
}

CARD:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Store card UID and validate card certificate (for PKI-cards)

Now only support contactless cards (UID).

Send request with card certificate and card uid to do_enroll and check status.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


CARD:1 logon:

POST /api/v1/logon/R94moMSOwAekT28PMCbSnuK8UJq0AxlP/do_logon
RequestsSend Smartcard UID and card certificate
Body
{
  "endpoint_session_id": "MDG133vYLaZIBuSvHFF5LfZtSApQHkaQ",
  "response": {
    "card_uid": "0e62f260aa610be177ba6c5d052ef002",
    "card_cert": "308205243082040ca003...64a5883aa073b4588"
  }
}
Responses200
Body
{
    "plugins": [],
    "msg": "Welcome",
    "status": "OK",
    "logon_process_id": "R94moMSOwAekT28PMCbSnuK8UJq0AxlP",
    "event_name": "TEST",
    "chains": [
        {
            "short_name": "",
            "apply_for_ep_owner": false,
            "image_name": "CARD_1.png",
            "grace_period": null,
            "methods": ["CARD:1"],
            "position": 0,
            "id_hex": "54e35a080c8a11e6b5cd080027983191",
            "is_trusted": null,
            "name": "Test-chain",
            "required_chain_id_hex": null,
            "is_enabled": true
        }
    ],
    "event_data_id": "",
    "repo_id": "54d11b360c8a11e6b5cd080027983191",
    "user_id": "ba94bcf442f0c148fc6a049c9470d1dd",
    "completed_methods": ["CARD:1"],
    "repo_obj_id": "54d6890e0c8a11e6b5cd080027983191",
    "login_session_id": "htNJc4zJq0DvtMR3jxqQXRzDKqdSB7vu",
    "data_id": "",
    "current_method": "CARD:1",
    "msgid": "AUCORE-2001",
    "user_name": "LOCAL\USER1"
}

CARD:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

CARD:1 logon steps:

  1. Send Smartcard UID and card certificate (for PKI-cards) to do_logon and check status

Now only support contactless cards (UID) and certificate-based (PKI) cards. This method supports 1-N logon, you can define card UID in ‘unit_id’ parameter instead of user_name. Yes, you send card_uid twice. Second one is needed for not 1-N logon scenarios, card AP is not first method of the chain. Non 1-N logon is also supported.

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: R94moMSOwAekT28PMCbSnuK8UJq0AxlP

ID of the logon process


SMARTPHONE:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsGet QR to enrollFinish enroll after phone actions
Body
{
  "login_session_id": "KOYxcRUuuZxDsEhxiycof4XwcuI2lbwk"
}
Responses200
Body
{
  "msg": "Scan this QR code with the smartphone application",
  "msgid": "AUCORE-3003",
  "qrdata": "OOBDATAJgBFHPokfqPOxbVzvKrj61GcZDkHeYd0AWYT9x3qQ0ihO9rRktvpqmnyPdlP5efN/FgLhl5D03bU9NJ6OwnxfODK9p5VHXpKqRYfKJhS/hSL7E4weFC4iGP1M1a9DTKfiRN4/A6XprEbkAQceOZMGDdkzmsh7dUus+0owd3FwBnG7jkkfCAQ1rSeI5P1HFMuPsBCdOUFRbMv3Ju8kXLIQRNrHiotksOCtF2vh1ALN3S4fXoPfpC8Nu13uV3ZU7vU+RL5FuexRktRm3dnoDnT1WrTerDXGVRn3T6Ghlg9UkyxswtW1Ipu8N+7OWIT/4PlQ62mj1xGG2otpPE6qCpWPg==",
  "status": "MORE_DATA",
  "reason": "SMARTPHONE_SCAN_QR",
  "method_id": "SMARTPHONE:1"
}
Body
{
  "login_session_id": "KOYxcRUuuZxDsEhxiycof4XwcuI2lbwk"
}
Responses200
Body
{
  "msg": "",
  "reason": "",
  "status": "OK",
  "method_id": "SMARTPHONE:1"
}

SMARTPHONE:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

SMARTPHONE:1 enroll steps:

  1. Send empty request do_enroll to get QA code and check status. User should scan this QR code by application.

  2. To check status of enroll application should send empty request to do_enroll until status will not changed for failed or successful.

Error reasons:

  • SMARTPHONE_ENROLL_TIMEOUT

  • SMARTPHONE_WAITING_DATA

  • SMARTPHONE_SCAN_QR

  • SMARTPHONE_WRONG_V4_TEMPLATE

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


SMARTPHONE:1 logon online:

POST /api/v1/logon/6MwzQQ2AKGtTW0q0q2VEQ3tIs0Y6Py0n/do_logon
Requests1. Send push message to smartphone2a. Finish logon successfully2b. Finish logon failed
Body
{
  "endpoint_session_id": "MDG133vYLaZIBuSvHFF5LfZtSApQHkaQ"
}
Responses200
Body
{
  "reason": "SMARTPHONE_WAITING_DATA",
  "msgid": "AUCORE-2056",
  "msg": "Waiting for the smartphone data...",
  "chains": [
    {
      "id_hex": null,
      "is_enabled": true,
      "short_name": "",
      "grace_period": null,
      "image_name": "ANY.png",
      "is_trusted": null,
      "name": "TEST CHAIN",
      "methods": [
        "ANY"
      ],
      "apply_for_ep_owner": false,
      "position": 1000,
      "required_chain_id_hex": null
    }
  ],
  "current_method": "SMARTPHONE:1",
  "status": "MORE_DATA",
  "logon_process_id": "6MwzQQ2AKGtTW0q0q2VEQ3tIs0Y6Py0n",
  "event_name": "",
  "completed_methods": [],
  "event_data_id": "",
  "plugins": [],
  "method_id": "SMARTPHONE:1"
}
Body
{
  "endpoint_session_id": "MDG133vYLaZIBuSvHFF5LfZtSApQHkaQ"
}
Responses200
Body
{
    "user_name": "LOCAL\AG",
    "msgid": "AUCORE-2053",
    "status": "OK",
    "repo_id": "8c4749d20c7111e69e17080027983191",
    "chains": [
        {
            "id_hex": null,
            "is_enabled": true,
            "short_name": "",
            "grace_period": null,
            "image_name": "ANY.png",
            "is_trusted": null,
            "name": "TEST CHAIN",
            "methods": ["ANY"],
            "apply_for_ep_owner": false,
            "position": 1000,
            "required_chain_id_hex": null
        }
    ],
    "current_method": "SMARTPHONE:1",
    "repo_obj_id": "8c4d1b500c7111e69e17080027983191",
    "msg": "Authentication is accepted",
    "user_id": "187e62bd172488bea921e47ea2be0e7e",
    "login_session_id": "qeDTAoC66hrMIl28xfnfeGbUpNn8nJXR",
    "logon_process_id": "6MwzQQ2AKGtTW0q0q2VEQ3tIs0Y6Py0n",
    "event_name": "",
    "completed_methods": ["SMARTPHONE:1"],
    "event_data_id": "",
    "data_id": "",
    "plugins": [],
    "method_id": "SMARTPHONE:1"
}
Body
{
  "endpoint_session_id": "MDG133vYLaZIBuSvHFF5LfZtSApQHkaQ"
}
Responses200
Body
{
  "event_name": "",
  "current_method": "SMARTPHONE:1",
  "status": "FAILED",
  "reason": "SMARTPHONE_AUTH_REJECTED",
  "method_id": "SMARTPHONE:1",
  "completed_methods": [],
  "msg": "Auth rejected",
  "plugins": [],
  "msgid": "AUCORE-2054",
  "chains": [
    {
      "grace_period": null,
      "image_name": "ANY.png",
      "position": 1000,
      "apply_for_ep_owner": false,
      "id_hex": null,
      "short_name": "",
      "is_trusted": null,
      "methods": [
        "ANY"
      ],
      "is_enabled": true,
      "required_chain_id_hex": null,
      "name": "TEST CHAIN"
    }
  ],
  "logon_process_id": "3VXhH6liboHcD35uweditS3MGoLJxQVo",
  "event_data_id": ""
}

SMARTPHONE:1 logon online:
POST/api/v1/logon/{logon_process_id}/do_logon

SMARTPHONE:1 Online mode logon steps:

  1. Send empty request to do_logon to send push notification to smartphone. User should receive push message and he can approve or reject it.

  2. To check status of logon application should send empty request to do_logon until status will not changed for failed or successful.

Error reasons:

  • SMARTPHONE_SAME_TOTP

  • SMARTPHONE_WRONG_TOTP

  • SMARTPHONE_AUTH_CONFIRM_TIMEOUT

  • SMARTPHONE_AUTH_REJECTED

  • SMARTPHONE_LOGON_IN_PROGRESS

  • SMARTPHONE_WAITING_DATA

  • SMARTPHONE_NO_LOCATION

  • SMARTPHONE_INCORRECT_LOCATION

  • SMARTPHONE_TOTP_LOGON_DISABLED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: 6MwzQQ2AKGtTW0q0q2VEQ3tIs0Y6Py0n

ID of the logon process


SMARTPHONE:1 logon offline:

POST /api/v1/logon/X7F93FOgKJVoVBg7kgRgdTtc0UKAN2Tm/do_logon
RequestsEnter TOTP-password from smartphoneLogon failed
Body
{
  "endpoint_session_id": "oxBLoOk1WyIvAcuUv5xIENMgSoya1K0j",
  "response": {
    "totp": "053226"
  }
}
Responses200
Body
{
    "user_name": "LOCAL\AG",
    "msgid": "AUCORE-2001",
    "status": "OK",
    "repo_id": "bf6508400c7111e69e17080027983191",
    "chains": [
        {
            "id_hex": null,
            "is_enabled": true,
            "short_name": "",
            "grace_period": null,
            "image_name": "ANY.png",
            "is_trusted": null,
            "name": "TEST CHAIN",
            "methods": ["ANY"],
            "apply_for_ep_owner": false,
            "position": 1000,
            "required_chain_id_hex": null
        }
    ],
    "current_method": "SMARTPHONE:1",
    "repo_obj_id": "bf6d48340c7111e69e17080027983191",
    "msg": "Welcome",
    "user_id": "0524d36a32ced8ac9044fb62f79f60e5",
    "login_session_id": "sUne8w7x4E2VMifobJcxxoobdudkq9Sp",
    "logon_process_id": "X7F93FOgKJVoVBg7kgRgdTtc0UKAN2Tm",
    "event_name": "",
    "completed_methods": ["SMARTPHONE:1"],
    "event_data_id": "",
    "data_id": "",
    "plugins": []
}
Body
{
  "endpoint_session_id": "oxBLoOk1WyIvAcuUv5xIENMgSoya1K0j",
  "response": {
    "totp": "053229"
  }
}
Responses200
Body
{
  "msg": "Wrong TOTP password",
  "event_name": "",
  "msgid": "AUCORE-2028",
  "reason": "SMARTPHONE_WRONG_TOTP",
  "current_method": "SMARTPHONE:1",
  "chains": [
    {
      "grace_period": null,
      "image_name": "ANY.png",
      "position": 1000,
      "apply_for_ep_owner": false,
      "id_hex": null,
      "short_name": "",
      "is_trusted": null,
      "methods": [
        "ANY"
      ],
      "is_enabled": true,
      "required_chain_id_hex": null,
      "name": "TEST CHAIN"
    }
  ],
  "status": "FAILED",
  "plugins": [],
  "logon_process_id": "nJERAkt5172RyPdJWuenkyjZHVKG2NR0",
  "event_data_id": "",
  "completed_methods": []
}

SMARTPHONE:1 logon offline:
POST/api/v1/logon/{logon_process_id}/do_logon

SMARTPHONE:1 Offline mode logon steps:

  1. Send request with totp password from smartphone to do_logon and check status

Error reasons:

  • SMARTPHONE_SAME_TOTP

  • SMARTPHONE_WRONG_TOTP

  • SMARTPHONE_AUTH_CONFIRM_TIMEOUT

  • SMARTPHONE_AUTH_REJECTED

  • SMARTPHONE_LOGON_IN_PROGRESS

  • SMARTPHONE_WAITING_DATA

  • SMARTPHONE_NO_LOCATION

  • SMARTPHONE_INCORRECT_LOCATION

  • SMARTPHONE_TOTP_LOGON_DISABLED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: X7F93FOgKJVoVBg7kgRgdTtc0UKAN2Tm

ID of the logon process


SMS_OTP:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect request
Body
{
    "login_session_id":"rBT79CAz8AWh1o920OrHumx32iaToCU9",
    "response":
        {
            "mobile_phone" : "+123456789" // (optional, if missed phone from repository will be used)
        }
}
Responses200
Body
{
  "reason": "",
  "method_id": "SMS_OTP:1",
  "status": "OK",
  "msg": ""
}

SMS_OTP:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send empty request to do_enroll and check status.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


SMS_OTP:1 logon:

POST /api/v1/logon/T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv/do_logon
Requests1. Send message to user2. Enter password from SMS3. Enter password from SMS unsuccessfully
Body
{
  "endpoint_session_id": "eRPr3yB92MgYySHk8I8yj5twuuf3PAUa"
}
Responses200
Body
{
  "event_name": "",
  "current_method": "SMS_OTP:1",
  "reason": "OTP_WAITING_PASSWORD",
  "msgid": "AUCORE-2012",
  "completed_methods": [],
  "logon_process_id": "T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv",
  "plugins": [],
  "status": "MORE_DATA",
  "event_data_id": "",
  "msg": "OTP password sent, please specify",
  "chains": [
    {
      "short_name": "",
      "position": 1000,
      "id_hex": null,
      "required_chain_id_hex": null,
      "is_trusted": null,
      "image_name": "ANY.png",
      "is_enabled": true,
      "methods": [
        "ANY"
      ],
      "name": "TEST CHAIN",
      "apply_for_ep_owner": false,
      "grace_period": null
    }
  ]
}
Body
{
  "endpoint_session_id": "eRPr3yB92MgYySHk8I8yj5twuuf3PAUa",
  "response": {
    "answer": "246635"
  }
}
Responses200
Body
{
    "user_id": "dfd5acc4dc8fdb8c712d8b9c8e8a10ad",
    "user_name": "LDS\Admin",
    "data_id": "",
    "event_data_id": "",
    "status": "OK",
    "msgid": "AUCORE-2001",
    "completed_methods": ["SMS_OTP:1"],
    "msg": "Welcome",
    "repo_id": "4c8449de0c4f11e6b18c080027983191",
    "event_name": "",
    "chains": [
        {
            "short_name": "",
            "position": 1000,
            "id_hex": null,
            "required_chain_id_hex": null,
            "is_trusted": null,
            "image_name": "ANY.png",
            "is_enabled": true,
            "methods": ["ANY"],
            "name": "TEST CHAIN",
            "apply_for_ep_owner": false,
            "grace_period": null
        }
    ],
    "repo_obj_id": "11a2916c4521e14e83ad19b0165311d1",
    "user_mobile_phone": ["+12345678901"],
    "current_method": "SMS_OTP:1",
    "user_sid_hex": "0105000016ef19f498f9c6c5e52ce57b56b2314ba46e9bdd41d24e5d",
    "user_cn": "Admin",
    "logon_process_id": "T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv",
    "plugins": [],
    "user_sid": "S-1-384768500-3318151576-2078616805-1261548118-3717951140-1565446721",
    "login_session_id": "HG72YHJloobSOVuIQAobht2tSeSnvl6Z",
    "user_dn": "CN=Admin,CN=test"
}
Body
{
  "endpoint_session_id": "eRPr3yB92MgYySHk8I8yj5twuuf3PAUa",
  "response": {
    "answer": "795191"
  }
}
Responses200
Body
{
  "msg": "Incorrect answer. Please try again",
  "reason": "OTP_WRONG_PASSWORD",
  "current_method": "SMS_OTP:1",
  "plugins": [],
  "status": "MORE_DATA",
  "chains": [
    {
      "short_name": "",
      "id_hex": null,
      "is_enabled": true,
      "position": 1000,
      "image_name": "ANY.png",
      "methods": [
        "ANY"
      ],
      "required_chain_id_hex": null,
      "name": "TEST CHAIN",
      "grace_period": null,
      "apply_for_ep_owner": false,
      "is_trusted": null
    }
  ],
  "event_data_id": "",
  "event_name": "",
  "logon_process_id": "T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv",
  "msgid": "AUCORE-2015",
  "completed_methods": []
}

SMS_OTP:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

SMS_OTP:1 logon steps:

  1. Send empty request to do_logon to send sms

  2. Send request with password from received sms to do_logon and check status

Error reasons:

  • OTP_CANNOT_SEND

  • OTP_TOO_MANY_SENT

  • OTP_WAITING_PASSWORD

  • OTP_NO_PASSWORD

  • OTP_PASSWORD_EXPIRED

  • OTP_WRONG_PASSWORD

  • OTP_NO_EXPLICIT_RECIPIENT

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv

ID of the logon process


SMS_OTP:1 method call:

POST /api/v1/logon_method/SMS_OTP:1
RequestsCorrect request
Body
{
    "endpoint_session_id":"rBT79CAz8AWh1o920OrHumx32iaToCU9", (trusted endpoint required)
    "mobile_phone": "+123456789"
}
Responses200
Body
{
  "otp": "123456"
}

SMS_OTP:1 method call:
POST/api/v1/logon_method/SMS_OTP:1

SMS_OTP:1 method steps:

  1. Send recipient mobile phone in request and check OTP

TOTP:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect request
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "serial": "987654321",
    "otp": "472265"
  }
}
Responses200
Body
{
  "reason": "",
  "method_id": "TOTP:1",
  "status": "OK",
  "msg": ""
}

TOTP:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with token serial or secret to do_enroll and check status.

Error reasons:

  • TOTP_SCAN_QR

  • TOTP_PASSWORD_WRONG

TOTP auth_template is shared secret and acceptance period (oath default is 30 sec)

Request fields:

  • serial, string, optional

  • secret, hex or base32 string, optional, either serial or secret must be specified

  • is_base32_secret, optional, default False

  • period, optional, default 30

  • otp_format, optional, one of [dec4, dec6, dec7, dec8]

  • hash, optional, one of hashlib.algorithms_guaranteed

  • otp, string, optional

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


TOTP:1 logon:

POST /api/v1/logon/f0fzSCkoGcCFMJTDRalx5nnsC9zEYHBQ/do_logon
RequestsSimple TOTP password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "123456"
  }
}
Responses200
Body
{
    "event_data_id": "",
    "msgid": "AUCORE-2001",
    "logon_process_id": "f0fzSCkoGcCFMJTDRalx5nnsC9zEYHBQ",
    "login_session_id": "9QHUl8xbBNo4PUO6UXYzbHltNaMmNpSL",
    "current_method": "TOTP:1",
    "chains": [
    {
      "position": 1000,
      "short_name": "",
      "grace_period": null,
      "methods": [
        "ANY"
      ],
      "is_enabled": true,
      "name": "TEST CHAIN",
      "id_hex": null,
      "required_chain_id_hex": null,
      "is_trusted": null,
      "apply_for_ep_owner": false,
      "image_name": "ANY.png"
    }
    ],
    "repo_obj_id": "c0fd1ab20b0e11e6b224080027983191",
    "plugins": [],
    "msg": "Welcome",
    "status": "OK",
    "user_id": "84a0a279d391de4b2fd70ea38b46d3ce",
    "data_id": "",
    "event_name": "",
    "repo_id": "c0eeb0ee0b0e11e6b224080027983191",
    "completed_methods": [
    "TOTP:1"
    ],
    "user_name": "LOCAL\ADMIN"
}

TOTP:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

TOTP:1 logon steps:

  1. Send otp-password to do_logon and check status

Error reasons:

  • TOTP_PASSWORD_UNDEFINED

  • TOTP_WAIT_MINUTE

  • TOTP_PASSWORD_WRONG

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: f0fzSCkoGcCFMJTDRalx5nnsC9zEYHBQ

ID of the logon process


TOTP enrollment QR code:

POST /api/v1/logon_method/TOTP:1
Requestsexample 1
Body
{
  "endpoint_session_id": "a23as...34ff",
  "generate_authenticator": true
}
Responses200
Body
{
  "is_base32_secret": false,
  "otp_format": "dec6",
  "period": 30,
  "qrdata": "OTPDATAYhgSNT3/7Gt0m1Kwpu3kqEvaOhI75PHcbgV0qbPMm71puyQlli069SCMsJv31jqALnzZRlkm+2qB5YX8dYP0s9/6cda7JjlSHaMZBszOKi6vIDX9cDd2AgIw4P1th8ByWu89HDMGA3nv6SiFJ0cZNkSHVZO8bzF/u9en6e7T1HkEppXvtcgYFlOcRPkGVBfY19xtU1l3S7/QvaNymQFA8mtWlZbveztpSq943iy1LwS8NE0koi3noTabpOI3cR5CaEK62651X2FhIsB+z956TwaWixorNjAQhJTe1eezAYNAeKvh/CVObzfjC9fs+gLokXvVOK23rODyK3RnDnp1aQ==",
  "secret": "baf6eefdbde06858733798b6ac9f08748a4fca3d"
}

TOTP enrollment QR code:
POST/api/v1/logon_method/TOTP:1

Request body params:

  • endpoint_session_id: ‘a23as…34ff’ (hex string) - Endpoint session id

  • generate_authenticator: (boolean) always true

  • is_base32_secret: (boolean) - secret is Google Authenticator format of secret (Base32) or not


TOUCHID:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
Requestsenroll
Body
{
  "response": {
    "public_key": "2d2d2d2d2d424547494e205055424c4943204b45592d2d2d2d2d0a4d466b77457759484b6f5a497a6a3043415159494b6f5a497a6a30444151634451674145737a49594b7862494249524f70734b7068794d6634726f724a4950720a54475254424c4e5336704770514a4d4d7965444b5349776c39756d456f50506b4a504a79577255497353416c4c3837663964704b666173576c773d3d0a2d2d2d2d2d454e44205055424c4943204b45592d2d2d2d2d",
    "user_id": "501"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "TOUCHID:1"
}

TOUCHID:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request to do_enroll and check status.

Fields description:

public_key: RSA public key which can be used on server side to validate signature (hex encoded string)

user_id: ID of account which profile was used to storing key pair (hex encoded string)

Error reasons:

  • MISSING_PARAMETERS

UI uses Device Service by calling this url: https://127.0.0.1:8442/api/v1/touchid/enroll

NOTE:

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


TOUCHID:1 logon:

POST /api/v1/logon/do_logon
Requests1. Ask server for hash challenge2. Send signed hash challenge using private key of enrolled user to do_logon
Body
{
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
  "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
  "current_method": "TOUCHID:1",
  "reason": "TOUCHID_WAITING_AUTH_SIGNATURE",
  "event_data_id": "",
  "msgid": "AUCORE-2059",
  "plugins": [],
  "challenge": "66fd6ef831e4ec98957030be94189a78ca3c2986dbed57a3b97985d862c217af",
  "user_id": "501",
  "event_name": "TEST",
  "msg": "Waiting for an authentication response",
  "chains": [
    {
      "short_name": "",
      "required_chain_id_hex": null,
      "position": 0,
      "is_enabled": true,
      "methods": [
        "TOUCHID:1"
      ],
      "image_name": "TOUCHID_1.png",
      "grace_period": null,
      "name": "Test-chain",
      "id_hex": "42b312980c8911e69140080027983191",
      "apply_for_ep_owner": false,
      "is_trusted": null
    }
  ],
  "completed_methods": [],
  "status": "MORE_DATA"
}
Body
{
  "response": {
    "signature": "66fd6ef831e4ec98957030be94189a78ca3c2986dbed57a3b97985d862c217af"
  },
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
    "data_id": "",
    "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
    "current_method": "TOUCHID:1",
    "event_data_id": "",
    "user_id": "3a76753d7f931751c79fa05d80eb058e",
    "repo_id": "42987aa00c8911e69140080027983191",
    "msgid": "AUCORE-2001",
    "plugins": [],
    "repo_obj_id": "42a3962e0c8911e69140080027983191",
    "event_name": "TEST",
    "msg": "Welcome",
    "chains": [
        {
            "short_name": "",
            "required_chain_id_hex": null,
            "position": 0,
            "is_enabled": true,
            "methods": ["TOUCHID:1"],
            "image_name": "TOUCHID_1.png",
            "grace_period": null,
            "name": "Test-chain",
            "id_hex": "42b312980c8911e69140080027983191",
            "apply_for_ep_owner": false,
            "is_trusted": null
        }
    ],
    "user_name": "LOCAL\USER1",
    "completed_methods": ["TOUCHID:1"],
    "status": "OK",
    "login_session_id": "Cga6cvaMTaMTaDp5TLZHPOet29O808VL"
}

TOUCHID:1 logon:
POST/api/v1/logon/do_logon

  1. Send empty request to do_logon to ask server for hash challenge

  2. Send signed hash using private key of enrolled user to do_logon


U2F:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
Requests1. Ask server for registerRequests2. Forward registerRequests and signRequests to JSAPI, get registerResponse and forward to server
Body
{
  "response": {
    "userName": "user1"
  },
  "login_session_id": "xTIskntGShVlNfkAUiaZUXE7BR3xToue"
}
Responses200
Body
{
  "signRequests": [],
  "registerRequests": [
    {
      "version": "U2F_V2",
      "appId": "https://demo.yubico.com",
      "challenge": "2MSDiW84JXiIfSpUd72XebgBujs2WOA-UmuWzpyUQsk"
    }
  ],
  "method_id": "U2F:1",
  "msgid": "AUCORE-3004",
  "reason": "U2F_WAITING_REG_RESPONSE",
  "status": "MORE_DATA",
  "msg": "Waiting for the register response"
}
Body
{
  "response": {
    "registerResponse": {
      "registrationData": "BQQ_jNAqemWkTfI9uL4CVo3eQSNIMe66u-pasr8BMuu9maA764C7jDPqXMUWhw8_4tDxeUbM72VJH5fssT6F2vT5QKheRH3Tk0hCuJD94ZRHf0Nkg-JDmLOivamSUeVXvRJaBLOp7N-hhxvoxlChQ-CSzMDqrC7EZ7IqWvl7Ac3xejswggIcMIIBBqADAgECAgRyWMLqMAsGCSqGSIb3DQEBCzAuMSwwKgYDVQQDEyNZdWJpY28gVTJGIFJvb3QgQ0EgU2VyaWFsIDQ1NzIwMDYzMTAgFw0xNDA4MDEwMDAwMDBaGA8yMDUwMDkwNDAwMDAwMFowKzEpMCcGA1UEAwwgWXViaWNvIFUyRiBFRSBTZXJpYWwgMTQ4MDMzMjE1NzgwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASisDmTIlQxnUH6SFTVfKGN62nMmz5Nga45nzI-gRZDme8qlRRnPRV87L-18LzHiQhT7lXPPxogZvTVE5uTizELoxIwEDAOBgorBgEEAYLECgECBAAwCwYJKoZIhvcNAQELA4IBAQG8zBr5C3uVeBjVVaQzcWpgFqztyzEyw0EPNmFkEGwj2SqwbF0cLLaSmtQhSKoqOvOuU4k6aqFAyukyZZMVPZKqAP0Vh0sCMpRMzpDvEZjO3v6gh5Z8bIDmtQAJ5B2nnILyVpc7DA7taj3dUrZzNMD8v-bYjKdTsZJ_QzQstsewIPkoFOIRRtqta0iwkEFiX_cwR11IF-USGcQHKUBoMX65JP9nY6DzQ3XHplOD3bHUOHsCi2MqBZU-1fKOrQJpNP0w8cBQpSk_hsVTm7UiGW_FGrxrIKXfpGfCGICKDxCMfuWKIshu0HjP0pEhowAX1Ls1pie2SoK3-VEhYtkOFRLqMEUCIFnX5ZcO8ZWOKyF6R-tAse3rYdzwFBq4LZzEeXUwn6oMAiEAwNuC4mkjobmeyilaLM4twOAicm-R_x_YKzcQcXIx5cU",
      "clientData": "eyJ0eXAiOiJuYXZpZ2F0b3IuaWQuZmluaXNoRW5yb2xsbWVudCIsImNoYWxsZW5nZSI6IjFNX2hrbkxka0Ixb1hySFQxWUZqSHA5NDRpT2w4N2kwd1B5UUV0MW5DYzQiLCJvcmlnaW4iOiJodHRwczovL2RlbW8ueXViaWNvLmNvbSIsImNpZF9wdWJrZXkiOiIifQ"
    }
  },
  "login_session_id": "xTIskntGShVlNfkAUiaZUXE7BR3xToue"
}
Responses200
Body
{
  "reason": "",
  "status": "OK",
  "method_id": "U2F:1",
  "msg": "Enrollment is complete",
  "msgid": "AUCORE-3001"
}

U2F:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

U2F:1 enroll steps:

  1. Ask server for registerRequests by sending empty request to do_enroll

  2. Forward registerRequests and signRequests to JSAPI, get registerResponse and forward to server to do_enroll

  3. Check status of received response

Error reasons:

  • U2F_WAITING_REG_RESPONSE

  • U2F_NOT_ATTESTED

U2F AP uses camelCasing for parameters. Chrome JS-API (u2f.js) uses this scheme. You simply forward objects such as SignRequest to/from AP and JS-API.

How to build APPID from inside browser:

function getOriginFromUrl(url) {
    var re = new RegExp('^(https?://)[^/]*/?');
    var originarray = re.exec(url);
    if (originarray == null) return originarray;
    var origin = originarray[0];
    while (origin.charAt(origin.length - 1) == '/') {
        origin = origin.substring(0, origin.length - 1);
    }
    if (origin == 'http:' || origin == 'https:')
        return null;
    return origin;
}
var appId = getOriginFromUrl(window.location);
URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


U2F:1 logon:

POST /api/v1/logon/tvV9a4UNEf71yvZDxwJQ179SJnHQndmT/do_logon
Requests1. Ask server for signRequests2. Forward signRequests to JSAPI, get signResponse and forward to server
Body
{
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
  "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
  "current_method": "U2F:1",
  "reason": "U2F_WAITING_AUTH_RESPONSE",
  "event_data_id": "",
  "msgid": "AUCORE-2059",
  "plugins": [],
  "signRequests": [
    {
      "appId": "https://demo.yubico.com",
      "keyHandle": "qF5EfdOTSEK4kP3hlEd_Q2SD4kOYs6K9qZJR5Ve9EloEs6ns36GHG-jGUKFD4JLMwOqsLsRnsipa-XsBzfF6Ow",
      "version": "U2F_V2",
      "challenge": "NGX54sR5bgHSSJVs7ijQaMi_vV-lz48UqWW-XTlHgX4"
    }
  ],
  "event_name": "TEST",
  "msg": "Waiting for an authentication response",
  "chains": [
    {
      "short_name": "",
      "required_chain_id_hex": null,
      "position": 0,
      "is_enabled": true,
      "methods": [
        "U2F:1"
      ],
      "image_name": "U2F_1.png",
      "grace_period": null,
      "name": "Test-chain",
      "id_hex": "42b312980c8911e69140080027983191",
      "apply_for_ep_owner": false,
      "is_trusted": null
    }
  ],
  "completed_methods": [],
  "status": "MORE_DATA"
}
Body
{
  "response": {
    "signResponse": {
      "keyHandle": "qF5EfdOTSEK4kP3hlEd_Q2SD4kOYs6K9qZJR5Ve9EloEs6ns36GHG-jGUKFD4JLMwOqsLsRnsipa-XsBzfF6Ow",
      "signatureData": "AQAAAKowRAIgFrmzsrUHiUw2ixt20cXLjBRDo7-UoqWqZlNsFcXZL4ECIH45ALRE86ijsKPv_r3zmzhoE34N3NqzgvRJ1f49C1UA",
      "clientData": "eyJ0eXAiOiJuYXZpZ2F0b3IuaWQuZ2V0QXNzZXJ0aW9uIiwiY2hhbGxlbmdlIjoiZXYwd3dLR3l5bV9YamdZZkExd2tNT3Y4bGpsOHphS0F5WGdBV3gyUW91OCIsIm9yaWdpbiI6Imh0dHBzOi8vZGVtby55dWJpY28uY29tIiwiY2lkX3B1YmtleSI6IiJ9"
    }
  },
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
    "data_id": "",
    "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
    "current_method": "U2F:1",
    "event_data_id": "",
    "user_id": "3a76753d7f931751c79fa05d80eb058e",
    "repo_id": "42987aa00c8911e69140080027983191",
    "msgid": "AUCORE-2001",
    "plugins": [],
    "repo_obj_id": "42a3962e0c8911e69140080027983191",
    "event_name": "TEST",
    "msg": "Welcome",
    "chains": [
        {
            "short_name": "",
            "required_chain_id_hex": null,
            "position": 0,
            "is_enabled": true,
            "methods": ["U2F:1"],
            "image_name": "U2F_1.png",
            "grace_period": null,
            "name": "Test-chain",
            "id_hex": "42b312980c8911e69140080027983191",
            "apply_for_ep_owner": false,
            "is_trusted": null
        }
    ],
    "user_name": "LOCAL\USER1",
    "completed_methods": ["U2F:1"],
    "status": "OK",
    "login_session_id": "Cga6cvaMTaMTaDp5TLZHPOet29O808VL"
}

U2F:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

U2F:1 logon steps:

  1. Send empty request to do_logon to ask server for signRequests

  2. Forward signRequests to JSAPI, get signResponse, send it to do_logon and check status

Error reasons:

  • U2F_ALL_TOKENS_COMPROMISED

  • U2F_NO_TOKENS

  • U2F_WAITING_AUTH_RESPONSE

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: tvV9a4UNEf71yvZDxwJQ179SJnHQndmT

ID of the logon process


VOICE:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
Requestsexample 1
Body
{
    "login_session_id":"rBT79CAz8AWh1o920OrHumx32iaToCU9",
    "response":
        {
            "mobile_phone" : "+123456789", // (optional, if missed phone from repository will be used)
            "pin": "12345"
        }
}
Responses200
Body
{
  "status": "OK",
  "reason": "",
  "msg": "",
  "method_id": "VOICE:1"
}

VOICE:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with pin to do_enroll and check status.

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


VOICE:1 logon:

POST /api/v1/logon/F1iJ4albUW81CqFzdZXekgdyPyB43YbY/do_logon
Requests1. Call to user2. Check call status3. Finish logon
Body
{
  "endpoint_session_id": "vqRVxFg79DEHCAJjoe0nJNBSMoibCZa9"
}
Responses200
Body
{
  "status": "MORE_DATA",
  "plugins": [],
  "msg": "Call has been initiated",
  "current_method": "VOICE:1",
  "completed_methods": [],
  "chains": [
    {
      "is_enabled": true,
      "apply_for_ep_owner": false,
      "is_trusted": null,
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "required_chain_id_hex": null,
      "image_name": "ANY.png",
      "grace_period": null,
      "short_name": "",
      "methods": [
        "ANY"
      ]
    }
  ],
  "reason": "VOICE_CALL_INITIATED",
  "msgid": "AUCORE-2077",
  "event_data_id": "",
  "event_name": "",
  "logon_process_id": "F1iJ4albUW81CqFzdZXekgdyPyB43YbY"
}
Body
{
  "endpoint_session_id": "vqRVxFg79DEHCAJjoe0nJNBSMoibCZa9"
}
Responses200
Body
{
  "status": "MORE_DATA",
  "plugins": [],
  "msg": "Call is in progress",
  "current_method": "VOICE:1",
  "completed_methods": [],
  "chains": [
    {
      "is_enabled": true,
      "apply_for_ep_owner": false,
      "is_trusted": null,
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "required_chain_id_hex": null,
      "image_name": "ANY.png",
      "grace_period": null,
      "short_name": "",
      "methods": [
        "ANY"
      ]
    }
  ],
  "reason": "VOICE_CALL_IN_PROGRESS",
  "msgid": "AUCORE-2073",
  "event_data_id": "",
  "event_name": "",
  "logon_process_id": "F1iJ4albUW81CqFzdZXekgdyPyB43YbY"
}
Body
{
  "endpoint_session_id": "vqRVxFg79DEHCAJjoe0nJNBSMoibCZa9"
}
Responses200
Body
{
    "user_name": "LOCAL\AG",
    "msgid": "AUCORE-2001",
    "status": "OK",
    "repo_id": "bf6508400c7111e69e17080027983191",
    "chains": [
        {
            "id_hex": null,
            "is_enabled": true,
            "short_name": "",
            "grace_period": null,
            "image_name": "ANY.png",
            "is_trusted": null,
            "name": "TEST CHAIN",
            "methods": ["ANY"],
            "apply_for_ep_owner": false,
            "position": 1000,
            "required_chain_id_hex": null
        }
    ],
    "current_method": "VOICE:1",
    "repo_obj_id": "bf6d48340c7111e69e17080027983191",
    "msg": "Welcome",
    "user_id": "0524d36a32ced8ac9044fb62f79f60e5",
    "login_session_id": "sUne8w7x4E2VMifobJcxxoobdudkq9Sp",
    "logon_process_id": "F1iJ4albUW81CqFzdZXekgdyPyB43YbY",
    "event_name": "",
    "completed_methods": ["VOICE:1"],
    "event_data_id": "",
    "data_id": "",
    "plugins": []
}

VOICE:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

VOICE:1 logon steps:

  1. Send empty request to do_logon to make a call to user. User should receive call and enter pin from it.

  2. To check status of logon application should send empty request to do_logon until status will not changed for failed or successful.

Error reasons:

  • VOICE_PIN_NOT_VERIFIED

  • VOICE_CALL_IN_PROGRESS

  • VOICE_PIN_EXPIRED

  • VOICE_CANNOT_CALL

  • VOICE_CALL_INITIATED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: F1iJ4albUW81CqFzdZXekgdyPyB43YbY

ID of the logon process


PASSWORD:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect request
Body
{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "password": "super_password"
  }
}
Responses200
Body
{
  "reason": "",
  "method_id": "PASSWORD:1",
  "status": "OK",
  "msg": ""
}

PASSWORD:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request with password to do_enroll and check status.

Error reasons:

  • PASSWORD_BAD_CONFIRMATION

  • PASSWORD_EMPTY

  • PASSWORD_UNCHANGED

  • PASSWORD_TOO_SHORT

  • PASSWORD_TOO_SIMPLE

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


PASSWORD:1 logon:

POST /api/v1/logon/TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS/do_logon
RequestsSimple virtual password doLogon
Body
{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "my-password"
  }
}
Responses200
Body
{
  "user_id": "4f34e2882991440ddd0fd515e0d0236c",
  "completed_methods": [
    "PASSWORD:1"
  ],
  "repo_id": "3c9c1fd8061e11e6b224080027983191",
  "status": "OK",
  "repo_obj_id": "3caa08a0061e11e6b224080027983191",
  "event_data_id": "",
  "logon_process_id": "jImh3267QFyZ9pXjSGPj5EIhpKKU8Xu9",
  "user_name": "LOCAL\ADMIN",
  "login_session_id": "TmPxkC98vF4FGhDvqedjXItbmGjVJYTD",
  "plugins": [],
  "event_name": "",
  "chains": [
    {
      "name": "TEST CHAIN",
      "position": 1000,
      "id_hex": null,
      "apply_for_ep_owner": false,
      "required_chain_id_hex": null,
      "methods": [
        "ANY"
      ],
      "short_name": "",
      "image_name": "ANY.png",
      "is_trusted": null,
      "is_enabled": true,
      "grace_period": null
    }
  ],
  "current_method": "PASSWORD:1",
  "msgid": "AUCORE-2001",
  "msg": "Welcome",
  "data_id": ""
}

PASSWORD:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

PASSWORD:1 logon steps:

  1. Send password to do_logon and check status

Error reasons:

  • PASSWORD_UNDEFINED

  • PASSWORD_WRONG

  • PASSWORD_EXPIRED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS

ID of the logon process


VOICE_OTP:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
RequestsCorrect request
Body
{
    "login_session_id":"rBT79CAz8AWh1o920OrHumx32iaToCU9"
    'mobile_phone' : '+123456789' (optional, if missed phone from repository will be used)
}
Responses200
Body
{
  "reason": "",
  "method_id": "VOICE_OTP:1",
  "status": "OK",
  "msg": ""
}

VOICE_OTP:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

  1. Send request to do_enroll and check status.
URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


VOICE_OTP:1 logon:

POST /api/v1/logon/T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv/do_logon
Requests1. Send message to user2. Enter password from call3. Enter password from call unsuccessfully
Body
{
  "endpoint_session_id": "eRPr3yB92MgYySHk8I8yj5twuuf3PAUa"
}
Responses200
Body
{
  "event_name": "",
  "current_method": "VOICE_OTP:1",
  "reason": "OTP_WAITING_PASSWORD",
  "msgid": "AUCORE-2012",
  "completed_methods": [],
  "logon_process_id": "T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv",
  "plugins": [],
  "status": "MORE_DATA",
  "event_data_id": "",
  "msg": "OTP password sent, please specify",
  "chains": [
    {
      "short_name": "",
      "position": 1000,
      "id_hex": null,
      "required_chain_id_hex": null,
      "is_trusted": null,
      "image_name": "ANY.png",
      "is_enabled": true,
      "methods": [
        "ANY"
      ],
      "name": "TEST CHAIN",
      "apply_for_ep_owner": false,
      "grace_period": null
    }
  ]
}
Body
{
  "endpoint_session_id": "eRPr3yB92MgYySHk8I8yj5twuuf3PAUa",
  "response": {
    "answer": "246635"
  }
}
Responses200
Body
{
    "user_id": "dfd5acc4dc8fdb8c712d8b9c8e8a10ad",
    "user_name": "LDS\Admin",
    "data_id": "",
    "event_data_id": "",
    "status": "OK",
    "msgid": "AUCORE-2001",
    "completed_methods": ["VOICE_OTP:1"],
    "msg": "Welcome",
    "repo_id": "4c8449de0c4f11e6b18c080027983191",
    "event_name": "",
    "chains": [
        {
            "short_name": "",
            "position": 1000,
            "id_hex": null,
            "required_chain_id_hex": null,
            "is_trusted": null,
            "image_name": "ANY.png",
            "is_enabled": true,
            "methods": ["ANY"],
            "name": "TEST CHAIN",
            "apply_for_ep_owner": false,
            "grace_period": null
        }
    ],
    "repo_obj_id": "11a2916c4521e14e83ad19b0165311d1",
    "user_mobile_phone": ["+12345678901"],
    "current_method": "VOICE_OTP:1",
    "user_sid_hex": "0105000016ef19f498f9c6c5e52ce57b56b2314ba46e9bdd41d24e5d",
    "user_cn": "Admin",
    "logon_process_id": "T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv",
    "plugins": [],
    "user_sid": "S-1-384768500-3318151576-2078616805-1261548118-3717951140-1565446721",
    "login_session_id": "HG72YHJloobSOVuIQAobht2tSeSnvl6Z",
    "user_dn": "CN=Admin,CN=test"
}
Body
{
  "endpoint_session_id": "eRPr3yB92MgYySHk8I8yj5twuuf3PAUa",
  "response": {
    "answer": "795191"
  }
}
Responses200
Body
{
  "msg": "Incorrect answer. Please try again",
  "reason": "OTP_WRONG_PASSWORD",
  "current_method": "VOICE_OTP:1",
  "plugins": [],
  "status": "MORE_DATA",
  "chains": [
    {
      "short_name": "",
      "id_hex": null,
      "is_enabled": true,
      "position": 1000,
      "image_name": "ANY.png",
      "methods": [
        "ANY"
      ],
      "required_chain_id_hex": null,
      "name": "TEST CHAIN",
      "grace_period": null,
      "apply_for_ep_owner": false,
      "is_trusted": null
    }
  ],
  "event_data_id": "",
  "event_name": "",
  "logon_process_id": "T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv",
  "msgid": "AUCORE-2015",
  "completed_methods": []
}

VOICE_OTP:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

VOICE_OTP:1 logon steps:

  1. Send empty request to do_logon to initiate call

  2. Send request with password from call to do_logon and check status

Error reasons:

  • OTP_CANNOT_SEND

  • OTP_TOO_MANY_SENT

  • OTP_WAITING_PASSWORD

  • OTP_NO_PASSWORD

  • OTP_PASSWORD_EXPIRED

  • OTP_WRONG_PASSWORD

  • OTP_NO_EXPLICIT_RECIPIENT

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: T3Hc3fwHIN4pyJ9gEBaWC416gKRTANQv

ID of the logon process


VOICE_OTP:1 method call:

POST /api/v1/logon_method/VOICE_OTP:1
RequestsCorrect request
Body
{
    "endpoint_session_id":"rBT79CAz8AWh1o920OrHumx32iaToCU9", (trusted endpoint required)
    "mobile_phone": "+123456789"
}
Responses200
Body
{
  "otp": "3456"
}

VOICE_OTP:1 method call:
POST/api/v1/logon_method/VOICE_OTP:1

VOICE_OTP:1 method steps:

  1. Send recipient mobile phone in request and check OTP

WEBAUTH:1 enroll:

POST /api/v1/enroll/uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc/do_enroll
RequestsdoEnroll: Start enrolldoEnroll: Check status
Body
{
    "login_session_id": "CD506E53Mts35Qp2YI3gCWPgtjx6Kt4M",
    "response": {
        "idp_name": "Google OAuth 2.0",                  // REQUIRED: Identity provider (IdP) entry in Web authentication method settings
        "username_hint": "[email protected]",               // OPTIONAL: Hint is usable for some IdP (Google) to fill up "User name" field
        "final_redirection": {                           // REQUIRED: the redirection form which will be sent to browser after the user passed IdP authentication
            "action": "http://localhost/path?par=val",
            "method": "post",
            "id": "form1",
            "name": "formName",
            "data": {
                "field1": "state1",
                "field2": 12345
            }
        }
    }
}
Responses200
Body
For the first call:
{
    "status": "MORE_DATA",
    "msg": "Waiting for Identity provider response",
    "reason": "WEBAUTH_WAITING_DATA",
    "method_id": "WEBAUTH:1",
    "msgid": "AUCORE-3057"
}
Body
{
  "login_session_id": "CD506E53Mts35Qp2YI3gCWPgtjx6Kt4M"
}
Responses200
Body
For the next calls until the user will be authenticated by IdP:
{
    "status": "MORE_DATA",
    "msg": "Waiting for Identity provider response",
    "reason": "WEBAUTH_WAITING_DATA",
    "method_id": "WEBAUTH:1",
    "msgid": "AUCORE-3057"
}

The final result when the user passed through IdP authentication successfully:
{
    "status": "OK",
    "msg": "",
    "reason": "",
    "method_id": "WEBAUTH:1"
}

The final result when the user failed IdP authentication:
{
    "status": "FAILED",
    "msg": "",
    "reason": "",
    "method_id": "WEBAUTH:1"
}

WEBAUTH:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

WEBAUTH:1 enroll steps:

  1. Send “response” with redirection code to do_enroll and check status.
  2. Open the URL /webauth/{enroll_process_id}/enroll in browser.
  3. Go through authentication steps in browser
  4. Send “response” to do_enroll and check status.

Error reasons:

  • WEBAUTH_WAITING_DATA

  • WEBAUTH_FAILED

URI Parameters
HideShow
enroll_process_id
string (required) Example: uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc

ID of the enroll process


WEBAUTH:1 logon:

POST /api/v1/logon/qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz/do_logon
RequestsdoLogon: Start logondoLogon: Check result
Body
{
    "endpoint_session_id": "qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz",
    "method_id": "WEBAUTH:1",
    "response": {
        "final_redirection": {
            "action": "http://localhost/path?par=val",
            "method": "post",
            "id": "form1",          // OPTIONAL
            "name": "formName",     // OPTIONAL
            "data": {               // OPTIONAL form fields
                "field1": "state1",
                "field2": 12345
            }
        }
    }
}
Responses200
Body
For the first call:
{
    "event_data_id": "AUTHENTICATORS MANAGEMENT",
    "msgid": "AUCORE-3057",
    "category_id": "",
    "reason": "WEBAUTH_WAITING_DATA",
    "msg": "Waiting for IdP response",
    "linked_logon": false,
    "plugins": [ ],
    "event_name": "Authenticators Management",
    "status": "MORE_DATA",
    "chains": [
        {
            "tenant_id": "def0def0def0def0def0def0def0def0",
            "is_enabled": true,
            "image_name": "WEBAUTH_1.png",
            "name": "webauth",
            "id_hex": "b8476540b49411e7b93e000c294d5acc",
            "is_trusted": null,
            "apply_for_ep_owner": false,
            "short_name": "webauth",
            "position": 0,
            "methods": ["WEBAUTH:1"],
            "mfa_tags": [ ],
            "required_chain_id_hex": null,
            "grace_period": null
        }
    ],
    "completed_methods": [ ],
    "method_id": "WEBAUTH:1",
    "current_method": "WEBAUTH:1",
    "login_url": "https://testsp.ngrok.io/webauth/qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz/login",
    "logon_process_id": "qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz"
}
Body
{
  "endpoint_session_id": "qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz",
  "method_id": "WEBAUTH:1"
}
Responses200
Body
The final result when the user passed through IdP authentication successfully:
{
    "status": "OK",
    "msg": "Welcome!",
    "linked_logon": false,
    "plugins": [],
    "login_session_id": "Fdsoxy7pvH5AijDRxFdgfkgNuECghmGh",
    "completed_chain": {
        "id_hex": null,
        "tenant_id": "def0def0def0def0def0def0def0def0",
        "is_trusted": null,
        "is_enabled": true,
        "name": "TEST CHAIN",
        "short_name": "",
        "methods": [
            "ANY"
        ],
        "position": 1000,
        "apply_for_ep_owner": false,
        "image_name": "ANY.png",
        "required_chain_id_hex": null,
        "grace_period": null,
        "mfa_tags": []
    },
    "user_id": "6c5f9a6863d233ab6310602a8faee7f1",
    "user_name": "LOCAL\ADMIN",
    "repo_id": "2e0598aa5cf711e8bb2a0242ac130002",
    "repo_obj_id": "2e06ede05cf711e8bb2a0242ac130002",
    "msgid": "AUCORE-2001",
    "chains": [
        {
            "id_hex": null,
            "tenant_id": "def0def0def0def0def0def0def0def0",
            "is_trusted": null,
            "is_enabled": true,
            "name": "TEST CHAIN",
            "short_name": "",
            "methods": [
                "ANY"
            ],
            "position": 1000,
            "apply_for_ep_owner": false,
            "image_name": "ANY.png",
            "required_chain_id_hex": null,
            "grace_period": null,
            "mfa_tags": []
        }
    ],
    "current_method": "WEBAUTH:1",
    "completed_methods": [
        "WEBAUTH:1"
    ],
    "logon_process_id": "eurdv8XtHCYrUM6YgPkIQm3WMuF1Kwnb",
    "event_name": "",
    "event_type": "Generic",
    "event_data_id": "",
    "data_id": "",
    "category_id": "",
    "event_name_warning": "You are testing an empty event; it allows any method. If this is unexpected, you may have forgotten to send event_name parameter"
}

The final result when error:
{
    "status": "FAILED",
    "msg": "Web Authentication has failed",
    "linked_logon": false,
    "reason": "WEBAUTH_FAILED",
    "plugins": [],
    "msgid": "AUCORE-3058",
    "chains": [
        {
            "id_hex": null,
            "tenant_id": "def0def0def0def0def0def0def0def0",
            "is_trusted": null,
            "is_enabled": true,
            "name": "TEST CHAIN",
            "short_name": "",
            "methods": [
                "ANY"
            ],
            "position": 1000,
            "apply_for_ep_owner": false,
            "image_name": "ANY.png",
            "required_chain_id_hex": null,
            "grace_period": null,
            "mfa_tags": []
        }
    ],
    "current_method": "WEBAUTH:1",
    "completed_methods": [],
    "logon_process_id": "XqxaOgvchUZB1vdWAMxQ3opIzMhpZaFA",
    "event_name": "",
    "event_type": "Generic",
    "event_data_id": "",
    "data_id": "",
    "category_id": "",
    "event_name_warning": "You are testing an empty event; it allows any method. If this is unexpected, you may have forgotten to send event_name parameter"
}

WEBAUTH:1 logon:
POST/api/v1/logon/{logon_process_id}/do_logon

WEBAUTH:1 logon steps:

  1. Send “response” with redirection code to do_logon and check status.

  2. Open the URL /webauth/{logon_process_id}/login in browser

  3. Go through authentication steps in browser

  4. Send “response” with or without redirection parameters to do_logon and check status.

Error reasons:

  • WEBAUTH_WAITING_DATA

  • WEBAUTH_FAILED

URI Parameters
HideShow
logon_process_id
32 symbol id (required) Example: qC3pQSmnA4Lto7JxTEQ7pn9DwSM5Vboz

ID of the logon process


WINHELLO:1 enroll:

POST /api/v1/enroll/JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX/do_enroll
Requestsenroll
Body
{
  "response": {
    "pkey": "66fd6ef831e4ec98957030be94189a78ca3c2986dbed57a3b97985d862c217af",
    "id": "c1e1c72a9bd070b4088f02b5df5f89abecad1b7ecced50da62542f8c794b8fb7",
    "user_sid": "0105000000000005150000008fabdc762a5e01157827e7a08c040000",
    "account_name": "abcdef"
  },
  "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H"
}
Responses200
Body
{
  "msgid": "AUCORE-3001",
  "reason": "",
  "msg": "Enrollment is complete",
  "status": "OK",
  "method_id": "WINHELLO:1"
}

WINHELLO:1 enroll:
POST/api/v1/enroll/{enroll_process_id}/do_enroll

Send request to do_enroll and check status.

Fields description: pkey: RSA public key which can be used on server side to validate signature (hex encoded string) id: Key pair ID. Can be used for quick checking that user provide correct finger (string) user_sid: SID of account which profile was used to storing key pair (hex encoded string)

Error reasons:

  • MISSING_PARAMETERS

UI uses Device Service by calling this url: https://127.0.0.1:8442/api/v1/wh/enroll

URI Parameters
HideShow
enroll_process_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the enroll process


WINHELLO:1 logon:

POST /api/v1/logon/do_logon
Requests1. Ask server for hash challenge2. Send signed hash challenge using private key of enrolled user to do_logon
Body
{
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
    "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
    "current_method": "WINHELLO:1",
    "reason": "WINHELLO_WAITING_AUTH_SIGNATURE",
    "event_data_id": "",
    "msgid": "AUCORE-2059",
    "plugins": [],
    "challenge": '66fd6ef831e4ec98957030be94189a78ca3c2986dbed57a3b97985d862c217af',
    "event_name": "TEST",
    "msg": "Waiting for an authentication response",
    "chains": [
        {
            "short_name": "",
            "required_chain_id_hex": null,
            "position": 0,
            "is_enabled": true,
            "methods": ["WINHELLO:1"],
            "image_name": "WINHELLO_1.png",
            "grace_period": null,
            "name": "Test-chain",
            "id_hex": "42b312980c8911e69140080027983191",
            "apply_for_ep_owner": false,
            "is_trusted": null
        }
    ],
    "completed_methods": [],
    "status": "MORE_DATA"
}
Body
{
  "response": {
    "signature": "66fd6ef831e4ec98957030be94189a78ca3c2986dbed57a3b97985d862c217af",
    "id": "c1e1c72a9bd070b4088f02b5df5f89abecad1b7ecced50da62542f8c794b8fb7",
    "user_sid": "0105000000000005150000008fabdc762a5e01157827e7a08c040000"
  },
  "endpoint_session_id": "4CkX5jecFnGrv4wIoP83ADpVORjk7zqZ"
}
Responses200
Body
{
    "data_id": "",
    "logon_process_id": "tvV9a4UNEf71yvZDxwJQ179SJnHQndmT",
    "current_method": "WINHELLO:1",
    "event_data_id": "",
    "user_id": "3a76753d7f931751c79fa05d80eb058e",
    "repo_id": "42987aa00c8911e69140080027983191",
    "msgid": "AUCORE-2001",
    "plugins": [],
    "repo_obj_id": "42a3962e0c8911e69140080027983191",
    "event_name": "TEST",
    "msg": "Welcome",
    "chains": [
        {
            "short_name": "",
            "required_chain_id_hex": null,
            "position": 0,
            "is_enabled": true,
            "methods": ["WINHELLO:1"],
            "image_name": "WINHELLO_1.png",
            "grace_period": null,
            "name": "Test-chain",
            "id_hex": "42b312980c8911e69140080027983191",
            "apply_for_ep_owner": false,
            "is_trusted": null
        }
    ],
    "user_name": "LOCAL\USER1",
    "completed_methods": ["WINHELLO:1"],
    "status": "OK",
    "login_session_id": "Cga6cvaMTaMTaDp5TLZHPOet29O808VL"
}

WINHELLO:1 logon:
POST/api/v1/logon/do_logon

WINHELLO:1 logon steps:

  1. Send empty request to do_logon to ask server for hash challenge

  2. Send signed hash using private key of enrolled user to do_logon


Method FIDO 2.0 - Getting a challenge and verify signature

Get challenge and verify signature api during FIDO2:1 enrollment. This api can be used by WebAuthn (FIDO2)

Get challenge and verify signature during FIDO2 enroll:

POST /api/v1/logon_method/FIDO2:1/enroll/uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc
Requestsexample 1example 2
Body
{
    "displayName": "LOCAL\ADMIN",
    "username": "LOCAL\ADMIN"
}
Responses200
Body
{
    "challenge": "1c71a0d37c7332b3e2aee5dd8b79f77e067b3c22",
    "pubKeyCredParams": [
                            {"alg": -7, "type": "public-key"},
                            {"alg": -257, "type": "public-key"}
                        ],
    "rp": {"id": None, "name": "172.17.0.1"},
    "status": "ok",
    "user": {
                "displayName": "LOCAL\ADMIN",
                "id": "22196673abcc0bb4",
                "name": "LOCAL\ADMIN"
            }
}
Body
{
  "rawId": "ZdoiW-h2UKZYFDkh0Zrs-p2DeNfFaieg11H0nWz5",
  "id": "ZdoiW-h2UKZYFDkh0Zrs-p2DeNfFaieg11H0nWz5",
  "response": {
    "clientDataJSON": "eyJjaGFsbGVuZ2UiOiJmZDgwNmFhYTIwNDhkMTdlNmQwNDQ1OTQ4ZDZlNGM",
    "attestationObject": "o2NmbXRoZmlkby11MmZnYXR0U3RtdKJjc2lnWEgwRgIhAJmQJ0UWURa"
  }
}
Responses200
Body
{
  "status": "ok",
  "errorMessage": ""
}

Get challenge and verify signature during FIDO2 enroll:
POST/api/v1/logon_method/FIDO2:1/enroll/{proc_id}

  1. Send request
URI Parameters
HideShow
proc_id
string (required) Example: uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc

ID of the enroll process

displayName
string (required) Example: 'LOCAL\ADMIN'

Display name of User

username
string (required) Example: 'LOCAL\ADMIN'

Username


Get challenge and verify signature during FIDO2 logon:

POST /api/v1/logon_method/FIDO2:1/logon/uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc
Requestsexample 1example 2
Body
{
    "displayName": "LOCAL\ADMIN",
    "username": "LOCAL\ADMIN"
}
Responses200
Body
{
  "status": "ok",
  "challenge": "dddda6ea311a0d2382bcb9d914d431639831d91d",
  "rpId": "localhost",
  "allowCredentials": [
    {
      "id": "ZdoiW-h2UKZYFDkh0Zrs-p2DeNfFaieg11H0nWz5_8iZ4olH6ewoanUs0C5hpFA39Vh",
      "transports": [
        "usb",
        "nfc",
        "ble"
      ],
      "type": "public-key"
    }
  ],
  "credential": {}
}
Body
{
  "rawId": "ZdoiW-h2UKZYFDkh0Zrs-p2DeNfFaieg11H0nWz5",
  "id": "ZdoiW-h2UKZYFDkh0Zrs-p2DeNfFaieg11H0nWz5",
  "response": {
    "clientDataJSON": "eyJjaGFsbGVuZ2UiOiJlODQzNWRlMzBiOTg2OTdDo1MDAwIiwidHlwZS",
    "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MBAAABBA",
    "signature": " MEUCIQDy16gFMzHriknyjmN0czB4dg_YlC10ofcOo0dypmcYYQIgcNRSqRcwWx5AMhO5DgsvhF",
    "userHandle": null
  },
  "getClientExtensionResults": {}
}
Responses200
Body
{
  "status": "ok",
  "errorMessage": ""
}

Get challenge and verify signature during FIDO2 logon:
POST/api/v1/logon_method/FIDO2:1/logon/{proc_id}

  1. Send request
URI Parameters
HideShow
proc_id
string (required) Example: uDlY59KIE89Ez5oQRKVnymjxcxyAFxLc

ID of the logon process

displayName
string (required) Example: 'LOCAL\ADMIN'

Display name of User

username
string (required) Example: 'LOCAL\ADMIN'

Username


Method Windows Hello - Get user account details

Read user details. Requires login_session_id of any user authenticated to Helpdesk or Authenticators Management event.

Read user details:

POST /api/v1/logon_method/WINHELLO:1/account_details/4f34e2882991440ddd0fd515e0d0236c/get
Responses200
Body
{
  "account_name": "Test",
  "is_ad_user": false
}

Read user details:
POST/api/v1/logon_method/WINHELLO:1/account_details/{user_id}/get

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o

OOB Logon

Out-of-band authentication.

OOB logon procedure from the point of view of “custom SSH server” or “Windows Client”.

  1. User connects to SSH server. The server asks user_name.

  2. SSH server starts OOB logon process. Pass user_name, grab oob_secret. You need endpoint_session, as normal endpoint.

  3. Periodically (5-10 seconds) check the status of oob logon process.

    Meanwhile, user opens "aucore-server/oob/{login_url}, sees WebUI logon page and logons. User can’t change user_name on WebUI login page.

    SSH server may grab login_url and ask user to open it. Another option is to use “Authentication Agent” running on user’s device (computer).

  4. As soon as the answer is “success: True”, SSH server resumes its normal login into the shell.

    AuCore server returns user.data[event.type], such as OS_PASSWORD. Windows Client needs real user password to perform domain login (event.type OS_LOGON)

OOB logon procedure from the point of view of “Authentication Agent”. Differences:

  • no endpoint_session is needed

  • user_name is not required, any string is possible. User may change user_name in WebUI logon page.

  1. User starts Authentication Agent.

  2. Agent creates OOB logon process, grabs oob_secret and logon_url.

  3. Agent opens logon_url in browser, user does login.

  4. Periodically the agent checks the status of oob logon process.

  5. As soon as the answer is “success: True”, the agent registers itself in OOB Daemon by using oob_secret.

    AuCore server does not return user.data[event.type] (OS_PASSWORD).

    AuCore server returns user_name. The agent may check that user_name is what the agent expects. The format of user_name: TENANT\REPO\USER or REPO\USER depending on multitenancy is ON or OFF.

Start new OOB login process:

POST /api/v1/oob
Requestsexample 1
Body
{
    "endpoint_session_id": "xxx",
    "event": "SSH",
    // "user" or "repo\user", "tenant\repo\user"
    "user_name": "user",
    // by default "TOP"
    "tenant_name: "MARIYA"
}
Responses200
Body
{
    "logon_url": "H8G-GUW",
    "oob_secret": "5CyUkh6i",
    "user": "TOP\LOCAL\USER1"
}

Start new OOB login process:
POST/api/v1/oob

Creates the process and returns “secret” and “logon_url”. AuCore server notifies user’s Authentication Agent through OOB Daemon. User’s agent opens logon_url in a browser.


Check oob logon status:

POST /api/v1/oob/get
Requestsexample 1
Body
{
    "oob_secret": "5CyUkh6i",
    "endpoint_session_id": "xxx",
}
Responses200200
Body
{
    "success": False
}
Body
{
    "success": True,
    "user": "TOP\LOCAL\USER1"
    "event_data_id": "OSLogon"
    "data": {"password": "shp1she mAst flo"}
}

Check oob logon status:
POST/api/v1/oob/get

This is “get” implemented as POST to hide oob_secret from nginx.log. Otherwise, oob_secret is logged as part of URL. For “Authentication Agent” event, no user data returned and user may be different.


OOB Daemon API. Register and wait for command:

POST /oob-daemon/agent
Requestsexample 1
Body
{
  "oob_secret": "5CyUkh6i"
}
Responses403200200
Body
"No such oob process"
Body
{
  "command": "NOOP"
}
Body
{
    "command": "OPEN"
    "logon_url": "OPE-NME"
}

OOB Daemon API. Register and wait for command:
POST/oob-daemon/agent

logon_url must be opened as “https://aucore-server/oob/{logon_url}”. The Agent must recognize commands “OPEN” and “NOOP”. Any other command must be ignored, agent MUST NOT send POST with same secret (“s”) and exit poll loop. Other commands may be “DESTROYED”, “OVERRIDEN BY ANOTHER AGENT” and more. Do not interpret, just log such commands for debug.

The agent MAY send 2nd parallel POST with same secret. 1st POST will got “OVERRIDEN BY PARALLEL REGISTRATION”. That said, there is maximum 1 opened POST connection between an agent and oob daemon.

The POST request returns “NOOP” after 60 seconds. The agent re-sends same POST immediately. If OOB process started during re-connection time, “OPEN” command would not be lost. The daemon will handle this situation.

Set request “response timeout” to 75 seconds and “connect timeout” to 7 seconds. If request times-out, re-send the POST. If you do not reconnect during 15 minutes, the daemon forget your secret (“s”) and the agent need re-login.


OOB Daemon. Check the daemon is OK:

GET /oob-daemon
Responses200
Body
"Daemon is running"

OOB Daemon. Check the daemon is OK:
GET/oob-daemon


OTP tokens

OATH tokens manager rest api. Requires login_session_id. Logged user must be member of FULL ADMINS or ENROLL ADMINS.

Get otp tokens with pagination:

GET /api/v1/otp_tokens?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX&offset=0&limit=50
Responses200
Body
{
  "tokens": [
    {
      "id": "d1a69020962e11e89e8f0242ac1b0002",
      "serial": "987654321",
      "type": "hotp",
      "otplen": 8,
      "time_step": null,
      "counter": 0,
      "hashlib": "",
      "ocrasuite": "",
      "public_id": "",
      "auth_template_id": null
    },
    {
      "id": "d1a6a04c962e11e89e8f0242ac1b0002",
      "serial": "987654323",
      "type": "pin",
      "otplen": 4,
      "time_step": null,
      "counter": null,
      "hashlib": "",
      "ocrasuite": "",
      "public_id": "",
      "auth_template_id": null
    },
    {
      "id": "c43028e8962e11e89e8f0242ac1b0002",
      "serial": "cc0000000000_1(cccccccccccc)",
      "type": "hotp",
      "otplen": 8,
      "time_step": null,
      "counter": null,
      "hashlib": "",
      "ocrasuite": "",
      "public_id": "cc0000000000",
      "auth_template_id": null
    }
  ]
}

Get otp tokens with pagination:
GET/api/v1/otp_tokens?login_session_id={login_session_id}&offset={offset}&limit={limit}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

otp_token_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the otp token

offset
int (optional) Example: 0

offset for pagination, default 0

limit
int (optional) Example: 50

page size, default 50, max 50


Create otp token:

POST /api/v1/otp_tokens?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
RequestsCreate hotp tokenCreate totp token
Body
{
  "hmac_key": "182903812382912802381049923198",
  "serial": "987654321",
  "type": "hotp",
  "otplen": 8,
  "counter": 10
}
Responses
Body
{
  "hmac_key": "182903812382912802381049923198",
  "serial": "987654321",
  "type": "totp",
  "otplen": 8,
  "time_step": 60,
  "hashlib":"sha256",
}
Responses

Create otp token:
POST/api/v1/otp_tokens?login_session_id={login_session_id}

Body params:

  • hashlib - one of ‘sha1’, ‘sha256’, ‘sha512’

  • type - one of ‘hotp’, ‘pin’, ‘totp’, ‘ocra’

  • otplen - length of otp, required

  • counter - the OTP generation counter

  • hmac_key - otp token’s secret, required

  • time_step - TOTP time step

  • public_id - yubikey public id

  • serial - id of token

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


Get otp token:

GET /api/v1/otp_tokens/f1be127607dc11e69bae080027983191?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "id": "d1a69020962e11e89e8f0242ac1b0002",
  "serial": "987654321",
  "type": "hotp",
  "otplen": 8,
  "time_step": null,
  "counter": 0,
  "hashlib": "",
  "ocrasuite": "",
  "public_id": "",
  "auth_template_id": null
}

Get otp token:
GET/api/v1/otp_tokens/{otp_token_id}?login_session_id={login_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

otp_token_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the otp token


Delete otp token:

DELETE /api/v1/otp_tokens/f1be127607dc11e69bae080027983191?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

Delete otp token:
DELETE/api/v1/otp_tokens/{otp_token_id}?login_session_id={login_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

otp_token_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the otp token


Enroll otp token:

POST /api/v1/otp_tokens/f1be127607dc11e69bae080027983191/enroll?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
RequestsEnroll otp token
Body
{
  "user_id": "f1be127607dc11e69bae080027983191"
}
Responses200
Body
{
  "id": "d1a69020962e11e89e8f0242ac1b0002",
  "serial": "987654321",
  "type": "hotp",
  "otplen": 8,
  "time_step": null,
  "counter": 0,
  "hashlib": "",
  "ocrasuite": "",
  "public_id": "",
  "auth_template_id": "f1be127607dc11e69bae080027983191",
  "owner": "User1"
}

Enroll otp token:
POST/api/v1/otp_tokens/{otp_token_id}/enroll?login_session_id={login_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

otp_token_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the otp token


Revoke otp token:

DELETE /api/v1/otp_tokens/f1be127607dc11e69bae080027983191/enroll?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

Revoke otp token:
DELETE/api/v1/otp_tokens/{otp_token_id}/enroll?login_session_id={login_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

otp_token_id
32 symbol id (required) Example: f1be127607dc11e69bae080027983191

ID of the otp token


Policies

Read object policies. Requires logged_session_id.

No writes. Setting policies is the task of admin UI.

Policies are defined for component. “Component policies” is dictionary of values. Value is any json-serializable object, maybe nested dict::

{
   "component_id":{
      "policy1":"value",
      "policy2":"value"
   }
}

Service returns effective policies. Effective is default component policies overridden by object-specific policies.

Read effective policies of user :

GET /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/effective_policy?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "policy": {
    "LoginOptions": {
      "component_id": "LoginOptions",
      "data": {
        "default_repos": [
          "LOCAL"
        ],
        "nondefault_repos": []
      }
    },
    "HelpdeskOptions": {
      "component_id": "HelpdeskOptions",
      "data": {
        "require_user_credentials": false
      }
    }
  }
}

Read effective policies of user :
GET/api/v1/users/{user_id}/effective_policy?login_session_id={login_session_id}

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


Read info about specific component of effective user policy

GET /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/effective_policy/TOTPMethod?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "policy": {
    "component_id": "TOTPMethod",
    "data": {
      "otp_window": 4,
      "otp_format": "dec6",
      "otp_period": 30,
      "use_key_uri_format_qr": false
    }
  }
}

Read info about specific component of effective user policy
GET/api/v1/users/{user_id}/effective_policy/{component}?login_session_id={login_session_id}

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session

component
string (required) Example: TOTPMethod

Component name


Read effective policies of endpoint :

GET /api/v1/endpoints/4f34e2882991440ddd0fd515e0d0236c/effective_policy?endpoint_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "policy": {
    "LoginOptions": {
      "component_id": "LoginOptions",
      "data": {
        "default_repos": [
          "LOCAL"
        ],
        "nondefault_repos": []
      }
    },
    "HelpdeskOptions": {
      "component_id": "HelpdeskOptions",
      "data": {
        "require_user_credentials": false
      }
    }
  }
}

Read effective policies of endpoint :
GET/api/v1/endpoints/{endpoint_id}/effective_policy?endpoint_session_id={endpoint_session_id}

Note: return default policies(not effective)

URI Parameters
HideShow
endpoint_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the endpoint

endpoint_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the endpoint session


Read info about specific component of endpoint effective policy

GET /api/v1/endpoints/4f34e2882991440ddd0fd515e0d0236c/effective_policy/TOTPMethod?endpoint_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "policy": {
    "component_id": "TOTPMethod",
    "data": {
      "otp_window": 4,
      "otp_format": "dec6",
      "otp_period": 30,
      "use_key_uri_format_qr": false
    }
  }
}

Read info about specific component of endpoint effective policy
GET/api/v1/endpoints/{endpoint_id}/effective_policy/{component}?endpoint_session_id={endpoint_session_id}

Note: return default policies(not effective)

URI Parameters
HideShow
endpoint_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the endpoint

endpoint_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the endpoint session

component
string (required) Example: TOTPMethod

Component name


SCIM

Advanced Authentication SCIM API doc

This is a limited implementation of System for Cross-domain Identity Management (SCIM). This SCIM Service Provider is intended to support just enough SCIM version 2.0 to allow external identity providers to sink in to an AA system.

For full information on SCIM 2.0 please refer to simplecloud.info

SCIM Resource Endpoints

SCIM User and Group endpoints are supported, however Self, Service Provider Config, Resource Types, Schema, Bulk, and Search or Query using HTTP POST are not supported.

Additional Unsupported SCIM features

  • meta.created, meta.location, or meta.version fields

  • meta.lastModified does not change on groups when group membership is modified.

  • meta.lastModified does not change when a PATCH is executed on a User.

  • Resource Versioning and ETags

  • [Modifying with Patch)(https://tools.ietf.org/html/rfc7644#section-3.5.2) does not support the “attributes” query parameter. The modified object is never returned. HTTP status code 204 (No Content) is the expected return value.

  • primary, type, display, and $ref are not stored or modifiable on phone and email attributes.

Authentication

When the SCIM repository is created a long term bearer token is issued, this bearer token is the preferred method for authenticating to the system. See SCIM Authentication and Authorization It is also possible to authenticate using standard Advanced Authentication mechanisms.
At the conclusion of the authentication a login session id is created. This session id may be passed to all SCIM calls using either the query parameter ‘login_session_id’ or adding the login_session_id directly to the JSON payload.

Repositories

The SCIM api provides Create, Read, Update, and Delete for users and groups in SCIM repositories. The api only provides read access to non-SCIM external repositories.

Common Issues

  • On calls that accept an {id} the passed id must match the id returned from a get or create call. This is an internal id, not the external id passed during create.

  • If there is more than one tenant on the AA system the caller must either use the bearer token issued at repository creation time or must pass the tenant_name parameter on all calls.

  • If there is more than one SCIM repository on the AA system the caller must either use the bearer token issued at repository creation time, or must pass the repo_name parameter on all calls.

  • The login_session_id, repo_name, and tenant_name parameters are not part of the SCIM standard and may not be supported by any client libraries your application consumes.

Custom attributes

To set custom attributes on a user use the following syntax:

POST https://aa.iam-saas.com/scim/v2/Users
Response:
{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:scim:schemas:extension:custom:1.0"],
   "userName": "sasopsadmin12", 
   "externalId": "sasopsadmin12", 
   "name": {
      "formatted": "SaaS OPS Bootstrap Administrator", 
      "familyName": "SaaS", 
      "middleName": "", 
      "givenName": "Operations Administrator"
   }, 
   "password": "1234567890abc", 
   "emails": [
      {"type": "other", "value": "[email protected]"}
   ], 
   "urn:scim:schemas:extension:custom:1.0": {
      "dn": "sasopsadmin12"
   }
}

To read custom attributes on a user the custom attribute name must be part of the attributes

GET https://aa.iam-saas.com/scim/v2/Users/u:13efe47dee95f360133a9aa40abaad55?attributes=urn:scim:schemas:extension:custom:1.0:dn

Response:
{
   "id": "u:13efe47dee95f360133a9aa40abaad55", 
   "externalId": "saasopsadmin1", 
   "userName": "[email protected]", 
   "meta": {"resourceType": "User"}, 
   "active": false, 
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 
   "emails": [{"type": "other", "value": "[email protected]"}]
   "urn:scim:schemas:extension:custom:1.0": { 
      "dn": "saasopsadmin" 
   } 
}

Read all users:

GET /scim/v2/Users

Read all users:
GET/scim/v2/Users

Supports pagination, and attributes control. Does not support filtering, or sorting. See the SCIM documentation for details on the protocol and schema.


Create user:

POST /scim/v2/Users

Create user:
POST/scim/v2/Users

Supports creating single valued custom attributes using “urn:scim:schemas:extension:custom:1.0” as the schema. See the SCIM documentation for details on the protocol and schema.


Read single user:

GET /scim/v2/Users/

Read single user:
GET/scim/v2/Users/

Supports attributes control. See the SCIM documentation for details on the protocol and schema.


Replace user:

PUT /scim/v2/Users/

Replace user:
PUT/scim/v2/Users/

Replaces all attributes of a User. It is recommended to GET a user, make your changes, then submit that user object to this.

See the SCIM documentation for details on the protocol and schema.


Delete user:

DELETE /scim/v2/Users/

Delete user:
DELETE/scim/v2/Users/

See the SCIM documentation for details on the protocol and schema.


Update user:

PATCH /scim/v2/Users/

Update user:
PATCH/scim/v2/Users/

Currently only supports changing a User’s password.

Example: { “schemas”: [ “urn:ietf:params:scim:schemas:core:2.0:User” ], “Operations”: [ { “op”: “replace”, “path”: “password”, “value”: “new password string” } ] }


List all groups:

GET /scim/v2/Groups

List all groups:
GET/scim/v2/Groups

Supports pagination See the SCIM documentation for details on the protocol and schema.


Create group:

POST /scim/v2/Groups

Create group:
POST/scim/v2/Groups

See the SCIM documentation for details on the protocol and schema.


Read single group:

GET /scim/v2/Groups/

Read single group:
GET/scim/v2/Groups/

See the SCIM documentation for details on the protocol and schema.


Update group:

PUT /scim/v2/Groups/

Update group:
PUT/scim/v2/Groups/

Not supported, will return HTTP status code 501, Not Implemented. Use patch to modify group and role membership. See the SCIM documentation for details on the protocol and schema.


Delete group:

DELETE /scim/v2/Groups/

Delete group:
DELETE/scim/v2/Groups/

Delete a group. Role deletion is not supported. See the SCIM documentation for details on the protocol and schema.


Update group:

PATCH /scim/v2/Groups/

Update group:
PATCH/scim/v2/Groups/

Currently only Group/Role membership may be modified. See the SCIM documentation for details on the protocol and schema.


Server Status

Read server status and version. Requires endpoint_session_id to read version.

Get server status and version:

GET /api/v1/status
Responses200
Body
{
  "status": "OK",
  "multitenancy_mode": false,
  "version": "5.4",
  "hosted_saas_mode": false
}

Get server status and version:
GET/api/v1/status

External monitors may check this URL as health indicator. Does not check that database is up and status of the license. Checks that the server is reachable and the web service is running.


Read exact server version, check license, FIPS mode state:

POST /api/v1/status
Requestsexample 1
Body
{
     // optional
     "endpoint_session_id": "PefYcnXk8QnqtYxXoaZjKES4pVrLaKzI",
     // optional
     "login_session_id": "IxJq1C5Gt6VxGeF65YjKl5R99Q70Lf9H",
     // optional
     "tenant_name": "TOP"
}
Responses200
Body
{
    "status": "OK/NO_LICENSE",
    "multitenancy_mode": false,
    "fips_mode": false,
    "version": "5.4-108",
}

Read exact server version, check license, FIPS mode state:
POST/api/v1/status

  • Returns HTTP code 200 only in case everything is OK.

  • Checks the license of tenant_name (“TOP”, by default).

  • Returns HTTP code 555 if NO_LICENSE.

  • Returns exact version number.

  • External monitors may check this URL as health indicator.

  • No endpoint session in the request - no exact version, still check the license.


Template Categories

Read authenticator categories. Requires login_session_id of any user authenticated to any event.

Read categories:

GET /api/v1/categories?login_session_id=B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o
Responses200
Body
{ 'categories': [
      {
        'id': 'd3ad2dd0dca211e68604000c29ecee77',
        'name': 'CAT1',
        'desc': 'category one'},
      {
        'id': 'd3ad3528dca211e68604000c29ecee77',
        'name': 'VAR',
        'desc': 'bar'}]
}

Read categories:
GET/api/v1/categories?login_session_id={login_session_id}

URI Parameters
HideShow
login_session_id
string (required) Example: B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o

Users

User lookup by name, list of users.

Requires login_session_id. Logged user must be member of FULL ADMINS or ENROLL ADMINS.

User lookup by given user name:

GET /api/v1/users?user_name=LOCAL\ADMIN&login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
      "obj_id": "3caa08a0061e11e6b224080027983191",
      "user_name": "LOCAL\ADMIN",
      "last_fail_at": null,
      "repo_id": "3c9c1fd8061e11e6b224080027983191",
      "repo_name": "LOCAL",
      "id": "4f34e2882991440ddd0fd515e0d0236c",
      "loginame": "ADMIN"
    }

User lookup by given user name:
GET/api/v1/users?user_name={user_name}&login_session_id={login_session_id}

URI Parameters
HideShow
user_name
string (required) Example: LOCAL\ADMIN

User name

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


List of users:

GET /api/v1/users?repo_name=BAZZ&page=0&login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "repo": {
    "id": "18cfb964dc2111e69288000c29ecee77",
    "name": "FOO"
  },
  "tenant": "TOP",
  "users": [
    {
      "id": "1897e91881407b0183bb2e6870d117ba",
      "name": "admin",
      "sid": "S-1-5-21-3303523795-413055529-2892985274-1104"
    },
    {
      "id": "221bbf7ac0dab7ccd25821f53f4276e0",
      "name": "Administrator",
      "sid": "S-1-5-21-3303523795-413055529-2892985274-500"
    }
  ]
}

List of users:
GET/api/v1/users?repo_name={repo_name}&page={page}&login_session_id={login_session_id}

LOCAL repo - all local users. LDAP repo - users listed in server database - those who tried to authenticate at least once.

URI Parameters
HideShow
repo_name
string (optional) Example: BAZZ
repo_id
hex (required) Example: fc73edbbc04048b79edc68521485c518

Either repo id or name required

page
int (optional) Example: 0

Page number starts with 0. Page size is 50000. Result is unsorted

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


User data

Access to data of the user.

Requires login_session_id of user or admin.

Data is defined for events. You may access data only of the event you are logged in. The event defines accessible data_id. Several events may share data_id. By default data_id = Event.name.upper().

Data permissions

  1. Restricted records - admin and user can read, but only admin can write (restricted write)

  2. Sensitive records - admin and user can write, but only user can read (restricted read)

Read all records of OSLogon data:

GET /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/data/OSLogon?login_session_id=rBT79CAz8AWh1o920OrHumx32iaToCU9
Responses200
Body
{
  "data": {
    "field3": {
      "inner": "dict",
      "is": {
        "possible": "at",
        "any": "level"
      }
    },
    "field1": "new_value"
  }
}

Read all records of OSLogon data:
GET/api/v1/users/{user_id}/data/OSLogon?login_session_id={login_session_id}

Read data. Data consists of records. You may read all records or specific one. Add login_session_id as query-string parameter.

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: rBT79CAz8AWh1o920OrHumx32iaToCU9

ID of the login session id


Delete all records of OSLogon data:

DELETE /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/data/OSLogon?login_session_id=rBT79CAz8AWh1o920OrHumx32iaToCU9
Responses200
Body
null

Delete all records of OSLogon data:
DELETE/api/v1/users/{user_id}/data/OSLogon?login_session_id={login_session_id}

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: rBT79CAz8AWh1o920OrHumx32iaToCU9

ID of the login session id


Delete password record only:

DELETE /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/data/OSLogon/password?login_session_id=rBT79CAz8AWh1o920OrHumx32iaToCU9
Responses200
Body
null

Delete password record only:
DELETE/api/v1/users/{user_id}/data/OSLogon/password?login_session_id={login_session_id}

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: rBT79CAz8AWh1o920OrHumx32iaToCU9

ID of the login session id


Modify data:

PATCH /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/data/OSLogon
RequestsUpdate fieldUpdate many fieldsModifications/additions are recursive and process sub-records
Body
{
  "login_session_id": "LRvql8GD946V7ryN8fesWBLhN1I7dpEe",
  "data": {
    "field1": "a value"
  }
}
Responses200
Body
null
Body
{
  "login_session_id": "LRvql8GD946V7ryN8fesWBLhN1I7dpEe",
  "data": {
    "field1": "new_value",
    "field2": null,
    "field3": {
      "inner": "dict",
      "is": {
        "possible": "at",
        "any": "level"
      }
    }
  }
}
Responses200
Body
null
Body
{
  "login_session_id": "LRvql8GD946V7ryN8fesWBLhN1I7dpEe",
  "data": {
    "field3": {
      "sub-record": "is added"
    }
  }
}
Responses200
Body
null

Modify data:
PATCH/api/v1/users/{user_id}/data/OSLogon

Create/modify record field1 for OSLogon data::

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user


Delete user:

POST /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/delete?login_session_id=rBT79CAz8AWh1o920OrHumx32iaToCU9
Responses200
Body
{}

Delete user:
POST/api/v1/users/{user_id}/delete?login_session_id={login_session_id}

  • clear all templates

  • clear any stored passwords

  • clear any other user specific data

  • member of ‘Full Admins’, ‘Enroll Admins’, ‘Tenant Admins’ can remove any user

  • normal user can delete itself only when ‘Delete Me’ policy is enabled

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: rBT79CAz8AWh1o920OrHumx32iaToCU9

ID of the login session id


User templates

Access to user’s authentication templates. Requires login_session_id of user or admin.

List of user's linked templates:

GET /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/templates?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
{
  "templates": [
    {
      "id": "3cb97b50061e11e6b224080027983191",
      "method_id": "PASSWORD:1",
      "method_title": "Password",
      "is_enrolled": true,
      "comment": "",
      "data": {},
      "category_id": ""
    },
    {
      "id": "83523194b70919672b1157bc929ed67a",
      "method_id": "CARD:1",
      "method_title": "Card",
      "is_enrolled": true,
      "comment": "",
      "data": {},
      "category_id": ""
    },
    {
      "id": "ff3f4e84203e6d7f56a0013074237071",
      "method_id": "SECQUEST:1",
      "method_title": "Security Questions",
      "is_enrolled": true,
      "comment": "",
      "data": {},
      "category_id": ""
    },
    {
      "id": "5194c010d968811da4ff47f843a3245e",
      "method_id": "HOTP:1",
      "method_title": "HOTP",
      "is_enrolled": true,
      "comment": "",
      "data": {},
      "category_id": ""
    }
  ]
}

List of user's linked templates:
GET/api/v1/users/{user_id}/templates?login_session_id={login_session_id}

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

login_session_id
string (required) Example: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX

ID of the login session


POST /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/templates
Requestsexample 1
Body
{
  "login_session_id": "LRvql8GD946V7ryN8fesWBLhN1I7dpEe",
  "enroll_process_id": "rlV6pSKXT4e0Ueq9hEXreL1ubkAdNYz2",
  "category_id": "hex or empty",
  "comment": "this is my comment"
}
Responses200
Body
{
  "auth_t_id": "3978beae0a3f11e68f20080027983191"
}

Create template, fill it from enroll session and link to user:
POST/api/v1/users/{user_id}/templates

User becomes owner of created template. Existing enrolled session is destroyed (no way to create 2 templates from same enroll session).

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user


POST /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/templates
Requestsexample 1
Body
{
    "login_session_id": "LRvql8GD946V7ryN8fesWBLhN1I7dpEe",
    "method_id": "EMAIL_OTP:1",
    "category_id": "hex or empty",
    "comment" : "this is my comment",
    //optional
    "unit_id " : "xxx"
}
Responses200
Body
{
  "auth_t_id": "b94292c20a3f11e68f20080027983191"
}

Create template without data and link to the user:
POST/api/v1/users/{user_id}/templates

Template should not be enrolled template and should be filled later by PUT

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user


POST /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/templates
Requestsexample 1
Body
{
  "auth_t_id": "3cb97b50061e11e6b224080027983191",
  "login_session_id": "LRvql8GD946V7ryN8fesWBLhN1I7dpEe"
}
Responses200
Body
{
  "auth_t_id": "3cb97b50061e11e6b224080027983191"
}

Link existing template to user.
POST/api/v1/users/{user_id}/templates

Passed logged_session_id must be of Share Authenticator admin After that operation, user may login by ‘xxx’ template owned by some other user, but user can’t change it.

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user


Fill auth template from enroll session and/or change comment:

PUT /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/templates/83523194b70919672b1157bc929ed67a
RequestsChange commentFill auth template
Body
{
  "login_session_id": "JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX",
  "comment": "my new comment"
}
Responses200
Body
null
Body
{
    "login_session_id": "JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX",
    "enroll_process_id": "hex",
    "comment": "12345",
}
Responses200
Body
null

Fill auth template from enroll session and/or change comment:
PUT/api/v1/users/{user_id}/templates/{auth_t_id}

URI Parameters
HideShow
user_id
string (required) Example: 4f34e2882991440ddd0fd515e0d0236c

ID of the user

auth_t_id
string (required) Example: 83523194b70919672b1157bc929ed67a

ID of the template


DELETE /api/v1/users/4f34e2882991440ddd0fd515e0d0236c/templates/83523194b70919672b1157bc929ed67a?login_session_id=JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Responses200
Body
null

Generated by aglio on 01 Mar 2021