• auth.as / Support / AUTH.AS service API description via HTTPS protocol

    AUTH.AS service API description via HTTPS protocol

    AUTH.AS system provides simple API to communicate with third-party services, systems and web applications, with the single function of one-time password check and return API response of this check success or fail.

     

    ”check_code” function

    Please, note, that all API query packets must be sent only via encrypted SSL-connection to 443 port (HTTPS). Do not use unsecured HTTP!

    ”check_code” function processes its queries at: https://console.auth.as/api/v1.0/check_code, let’s review the list of its query parameters.

     

    Technical description.

    ”check_code” function requires 3 mandatory parameters: the domain API Key, user email and one-time password (we do not accept and process regular user password!). Also, there is one extra parameter: format. HTTP-query format is POST.

    • ”api_key” Syntax: letters “a-z”, numbers “0-9”, fixed length 40 symbols.
    • ”email” is the user account email. Please, note, that emails for standard domains can belong to any domain, not just from the domain, specified for your account. If it’s an account for the ActiveDirectory-domain, the system automatically uses email address, specified in AD account profile.
    • ”code” is the one-time password – fixed length 6 digits numeric code, generated by your mobile application or by your physical token.
     
    API responses.

    API returns 2 standard responses, dependent on any parameters, mentioned above, check result.

    Code “200” will be returned only if all parameters were checked successfully: domain API Key, user email and one-time password.

    Code “401” will be returned if any case, mentioned below, appears:

    • Not all mandatory parameters were supplied;
    • The domain was not found with the API Key specified;
    • The user was not found in the domain specified;
    • The user is not assigned with any token;
    • The domain, the user or the token is locked;
    • Wrong one-time password;
    • Any other case, not covered in cases above.
     
    Response layout

    The extra parameter “format”, specified in the API POST-query, defines the response format. It is “text/plain” by default, or a plain text, in other words. The response will just have HTTP Status Code equal to “200” or “401”, which is clearly shows, if the check was successful or not.

    In case, format = ‘plain’, HTTP Status Code will always be “200”, but the response body will have actual check result “200” or “401”.

    In case, format = ‘json’, API response will have “application/json” type content, with detailed error description if any, and HTTP Status Code will be “200” or “401”, dependent on check success.

    ”format” parameter only changes the type of response content. It’s more detailed, in case of “json” and has more details for query-side.

     

    API test example using curl

    Please, note, that all of parameters below are fictional, these domains and users are not exist. Its only purpose is to demonstrate API responses in different cases.

     
    1. Query with JSON-type response, using incorrect one-time password:
    $ curl -X POST "https://console.auth.as/api/v1.0/check_code" \
    -d 'api_key=319660cf33a044b11231dab823284cc64c86f423' \
    -d 'email=firstname.lastname@domain.tld' \
    -d 'code=091572' \
    -d 'format=json'
     

    API response:

    {"response_code":401,"message":"Wrong token code for TimeBased algorithm"}

     
    2. Same, but with correct password. API response:

    {"response_code":200,"message":"200"}


    If we don’t supply the “format” parameter in the query above, API response is “200” or “401”, dependent on check success.

     

    Test example, using Microsoft PowerShell

     

    Run PowerShell and copy-paste the script text, mentioned below.

    Please, note, that “$email” and “$api_key” variables must be assigned with test values, and are also fictional in the text below.

      
    Import-Module activedirectory
    $email = "testuser1@testrcntec1.com"
    $api_key = "26d19660c5189044b111dab823284cc64c86f423"
    $code = Read-Host 'Please, enter your one-time password'
    $response = "0"
    $body = @{
           api_key = $api_key;
           email = $email;
           code = $code;}
    try { $response = Invoke-RestMethod -uri https://console.auth.as/api/v1.0/check_code -Method Post -Body $body }
    catch {}
    if ($response -ne "200") {echo "Login failed! Force logoff initiated..."}
    else {echo "Login successfull!"}
     

    Run the script in the Powershell window, enter one-time password, when prompted, and get the instant response in the same window.