cURL Ruby PHP

Introduction


# Use rubygems

gem install auth-armor


# Or use bundler

gem 'auth-armor'


# Then require the gem.

require 'auth-armor'

Auth Armor turns smart mobile devices into modern secure authenticators preventing attacks and un-authorized access.

Passwords and shared secrets are outdated and insecure. Account take-overs, password theft and breaches cost billions each year and are getting worse.

Use Auth Armor to protect websites, apps, backoffice and more with our simple API. Get running in minutes.

Authorization

To obtain an Access token, you must make a request to the Auth Armor OAuth2 server using the client_credentials OAuth2 grant.

Request

curl -X POST 
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
https://login.autharmor.com/connect/token
require "auth-armor"
AuthArmor::Client.new(client_id: "CLIENT_ID", client_secret: "CLIENT_SECRET")

<?php
  // Place your credentials in autharmor_creds.php. File should contain the following 3 lines:
  $this->client_id = "YourClientID";
  $this->client_secret = "YourClientSecret";
?>
Param Required Description
client_id Yes Client ID from Auth Armor
client_secret Yes Client Secret from Auth Armor
scope No Permissions that the token will be allowed to perform

Response

{
  "access_token":"eyJhbGciOiJSUzI1N...",
  "expires_in":600,
  "token_type":"Bearer",
  "scope":"aarmor.api.generate_invite_code aarmor.api.request_auth"
}

API Access

Both the client_id and client_secret are obtained via the developer dashboard located at https://dashboard.autharmor.com

Login then select or create a project. Navigate to the Api Access section and create a new api client. when you create a client, you are asked to give the client permissions, or scopes; select one more more scopes here. Please see the scopes section for more info. After client creation, you will be presented with a client_id and client_secret. Copy these values into your request.

Scopes

Scopes are permissions that the token will be allowed to perform. There are two scopes allowed. They are aarmor.api.generate_invite_code and aarmor.api.request_auth. When you create an api access client, you will be asked to select what scopes the client is allowed to perform. When requesting a token using that client, you can optionally leave the scope field blank. If left blank, all of the scopes that are assigned to the client will be applied to the token. If you specify the scopes in the token request, the token will then only have the scopes that were requested.

The access token returned will be used as a Bearer token for all the other requests.

Send Invite

Request


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "john_doe",
  "reference_id": "123456789"
}'
'https://api.autharmor.com/invite/request'

AuthArmor::Client.invite_request(
  nickname: "NICKNAME"
)
<php
  AuthArmor->invite_request(nickname: "NICKNAME")
?>

Before you can send auth requests, you must invite users to your project. You can use the invite API to request an invite, then send to your users. Auth Armor supports two ways users can be invited. Either methods first needs a call to the Auth Armor invite API

Param Required Description
nickname Yes This is a friendly display name for your user. It would be best to set the nickname to the username value or something similar so you can relate to your system. If your usernames are email addresses, consider masking the email address before using as a nickname to avoid personal information being stored in Auth Armor. You can search history using this ID
reference_id No This is an optional value that you can set to further cross reference your records. For example, you could set this value to your unique value in your system such as a UUID, a row ID, or some other value. You can search history using this ID.
reset_and_reinvite No Default is false. If you need to reset the current user and reinvite, set this flag to true. This will remove all mobile devices and/or active pending invites and create a new invite. Use caution when using this - it will reset any existing user with this nickname

QR code

AuthArmor::Client.generate_qr_code

Example

To use the QR code format, please format a json payload like below:

{
  "type":"profile_invite",
  "version":1,
  "format_id":1,
  "payload": {
    "aa_sig": "AA_SIG",
    "invite_code":"INVITE_CODE"
  }
}

A QR code can be generated and then scanned, much like many of the other authenticators out there. In the app, a user simply needs to scan the QR code to get setup for your project.

Then generate a QR code using this payload text. The QR code can then be scannedin the app

AuthArmor::Client.get_invite_link

Example

https://invite.autharmor.com/?i=aacc137b-e13e-4f35-9d3b-402d530d954c&aa_sig=6036145BEB43D02F61F5D41CE43F8BA5858ECBC2ED4AA7F35C8176BE37B92E68

In this method, the user can either click a link and follow invite instructions, or by using our client SDK, you can open a small pop-up window that will drive the invite process.

Invite Link format:

https://invite.autharmor.com/?i=INVITE_CODE>&aa_sig=AA_SIG

Response

Response

{
    "nickname": "sample test",
    "auth_profile_id": "706751cf-012d-4576-b639-654d0dfbdb5c",
    "invite_code": "43748ae...",
    "date_expires": "2020-07-11T17:18:56.3058075Z",
    "invite_type": "WebInviteAndOrQRCode",
    "aa_sig": "6433C0A...."
}
Param Description
nickname Echoing back this value from the request.
auth_profile_id This is the ID you will use to send an auth request. You must save this ID somewhere with your user records
invite_code This is the unique invite code for this invite.
date_expires This is when the invite will expire
invite_type This is the invite type, right now, the only option is "TBD".
aa_sig This is a special signature check value that helps prevent abuse.

Push Request

This is the API Endpoint to use for sending an auth request to your user(s).


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "sample_user",
  "action_name": "Login",
  "short_msg": "Login requested detected from IP: 192.160.0.1",
  "nonce": "some unique value of your choice here"
  }'
'https://api.autharmor.com/auth/request'

AuthArmor::Client.auth_request(
  nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here"
)
<?php
  AuthArmor->auth_request(
    nickname: "sample_user",
    action_name: "Login",
    short_msg: "This is a test message",
    nonce: "some unique value of your choice here"
  )
?>
Param Required Description
nickname Yes The nickname for the user you want to send this auth request to.
action_name Yes This is the action name that shows up in the push notification. This is the action the user is approving. Examples: “Login”, “Money Transfer”, “Account update”, etc. The min length is 2, and the max length is 25.
short_message Yes This is the short message that will appear in the app under the action name.
nonce No An optional value that is signed and returned in the request. This helps validate the response was from your request and no one has done a man-in-the-middle attack.
timeout_in_seconds No This is the amount of time you want to allow the auth to be valid before it expires. The min is 15, and max is 300. This is optional, and if not provided, will use the default time for the project.
accepted_auth_methods No This is an optional field. If you do not send it, Auth Armor will allow any type of auth method, including biometric, security key or even pin fall back from non-biometric devices.
origin_location_data No You can specify location data in the format of latitude and longitude. If provided, location details will show in the push message about the origin of the request.

If you send accepted_auth_methods param, you must provide a rule to go along with it. The accepted auth methods currently supported are: mobileDevice and securityKey.

Mobile Device

Using Mobile Device


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "sample_user",
  "action_name": "Login",
  "short_msg": "Login requested detected from IP: 192.160.0.1",
  "nonce": "some unique value of your choice here",
  "timeout_in_seconds": "120",
  "accepted_auth_methods": [
      {
        "name": "mobiledevice",      
        "rules": [
          {
            "name": "forcebiometric",
            "value": "true"
          }
        ]
      }
    ]
  }'
'https://api.autharmor.com/auth/request'

AuthArmor::Client.auth_request(
  nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here",
  accepted_auth_methods: "mobiledevice",
  forcebiometric: true
)
<?php
  AuthArmor->auth_request(
    nickname: "sample_user",
    action_name: "Login",
    short_msg: "This is a test message",
    nonce: "some unique value of your choice here",
    accepted_auth_methods: [{
      "name": "mobiledevice",
      "rules": {
        "name": "forcebiometric",
        "value": true
      }
    }]
  )
?>

The current rules for mobileDevice are forceBiometirc. This can either be set to true or false.

If forceBiometric is set to true, a mobile device will be required and biometrics will be required. Pin fallback and non-biometric devices will not be compatible with this method. Only biometrics, such as fingerprint or faceID will be allowed.

If forcebiometric is set to false, then a mobile device must be used, and a security key will not be allowed. Pin fallback and non-biometric devices using a pin will also be allowed

Security Key

Using Security Key


curl -XPOST
-H 'Authorization: Bearer TOKEN'
-H "Content-type: application/json"
-d '{
  "nickname": "sample_user",
  "action_name": "Login",
  "short_msg": "Login requested detected from IP: 192.160.0.1",
  "nonce": "some unique value of your choice here",
  "timeout_in_seconds": "120",
  "accepted_auth_methods": [
      {
        "name": "securitykey"     
      }
    ]
  }'
'https://api.autharmor.com/auth/request'

AuthArmor::Client.auth_request(
  nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here",
  accepted_auth_methods: "securitykey"
)
<?php
  AuthArmor->auth_request(
    nickname: "sample_user",
  action_name: "Login",
  short_msg: "This is a test message",
  nonce: "some unique value of your choice here",
    accepted_auth_methods: [{
      "name": "securitykey"
    }]
  )
?>

At this time, there are no rules for security keys.

If you set to security key, then mobile device will not be allowed, meaning no pin or biometrics are performed. Only a security key will be allowed. At this time, Auth Armor is using U2F. Full FIOD2 with user presence is coming soon.

Response

Param Description
auth_history_id This is the unique ID for the auth request.
response_code The response code result – 0 = unknown, 2 = success, 3 = declined, 4 = possible fraud attempt, 5 = timeout.
response_message The text representation of the result code.
authorized Boolean – if the auth request is authenticated.
auth_details Auth detail object, request and response details. More details defined in the table below.

Mobile Device Response


{
    "auth_history_id": "36f0d...",
    "response_code": 2,
    "response_message": "Success",
    "authorized": true,
    "auth_details": {
        "request_details": {
            "date": "2020-07-11T17:09:44.7860965Z",
            "auth_profile_details": {
                "auth_profile_id": "706751cf-012d-4576-b639-654d0dfbdb5c",
                "nickname": "john_doe",
                "ref_id": "123456789"
            },
            "origin_location_data": {
                "latitude": null,
                "longitude": null
            },
            "accepted_auth_methods": [
                {
                    "name": "MobileDevice",
                    "rules": [
                        {
                            "name": "ForceBiometric",
                            "value": false
                        }
                    ]
                }
            ]
        },
        "response_details": {
            "date": "2020-07-11T17:09:53.3862361Z",
            "auth_method": {
                "name": "MobileDevice",
                "usetype": "biometric"
            },
            "secure_signed_message": {
                "signed_data": "eyJtZXNzYWdlX2RhdGEi.....",
                "signature_data_details": {
                    "hash_value": "20bc1578...",
                    "signature_data": "{\"signature_data\":{\"counter\":17,\"signature_value\":\"MEUCIH...=\",\"challenge\":\"20bc15....\"},\"metaData\":{},\"version\":1,\"format\":1,\"key_Id\":\"\"}",
                    "auth_method_usetype": "biometric",
                    "signing_method": "AuthArmor_ECDsa",
                    "auth_method": "MobileDevice",
                    "hash_method": "Sha256"
                },
                "signed_data_type": "AuthResponse",
                "signature_validation_details": {
                    "public_key": "MFkwEwYHKoZI....==",
                    "key_size": "256",
                    "key_type": "EC",
                    "signing_algorithm": "SHA256",
                    "curve_type": "secp256r1",
                    "key_format": "x.509"
                },
            },
            "mobile_device_details": {
                "platform": "Android",
                "model": "Samsung A50s"
            }
        }
    }
}

Security Key Response


{
    "auth_history_id": "36f0d...",
    "response_code": 2,
    "response_message": "Success",
    "authorized": true,
    "auth_details": {
        "request_details": {
            "date": "2020-07-11T17:09:44.7860965Z",
            "auth_profile_details": {
                "auth_profile_id": "706751cf-012d-4576-b639-654d0dfbdb5c",
                "nickname": "john_doe",
                "ref_id": "123456789"
            },
            "origin_location_data": {
                "latitude": null,
                "longitude": null
            },
            "accepted_auth_methods": [
                {
                    "name": "SecurityKey",
                    "rules": []
                }
            ]
        },
        "response_details": {
            "date": "2020-07-11T17:09:53.3862361Z",
            "auth_method": {
                "name": "SecurityKey",
                "usetype": "u2f_securitykey"
            },
            "secure_signed_message": {
                "signed_data": "eyJtZXNzYWdlX2RhdGEi.....",
                "signature_data_details": {
                    "hash_value": "20bc1578...",
                    "signature_data": "{\"keyHandle\":\"bIap1cuTOBhl7VDd4Z56rFPkFJL0ow927f1kWI0SC3_oHjuTFxm7OUcHRrfavcjudIAkyuHiIC_WzKPAYaJPdA\",\"clientData\":\"eyJ0eXAiOiJuYXZpZ2F0b3IuaWQuZ2V0QXNzZXJ0aW9uIiwiY2hhbGxlbmdlIjoiNzQyNjJhZDU4NTYzMjQxZjQ0ZjNjNzFmZjZiYjA3MWQ2NDUyNTc5YmQzZjRkZWI4M2UzZmZiYzU1YWU4OThjZSIsIm9yaWdpbiI6ImFuZHJvaWQ6YXBrLWtleS1oYXNoOjRqMFpQRFNEMnJSWmlDV0JqR051aFRBNDNCcmZyV0orYitRc2E2aGZkaGsifQ\",\"signatureData\":\"AQAAAIYwRQIgGcCfCahRWxI5NbFvLY_0Nsc0hgAj7I67i9d0f4F3mCoCIQC4oByT5AW2GaqWOjeHLCr9pszmmG9pLqFBQEO7l1arQw\"}",
                    "auth_method_usetype": "u2f_securitykey",
                    "signing_method": "AuthArmor_ECDsa",
                    "auth_method": "SecurityKey",
                    "hash_method": "Sha256"
                },
                "signed_data_type": "AuthResponse",
                "signature_validation_details": {
                    "public_key": "MFkwEwYHKoZI....==",
                    "key_size": "256",
                    "key_type": "EC",
                    "signing_algorithm": "SHA256",
                    "curve_type": "secp256r1",
                    "key_format": "x.509"
                },
            },
            "mobile_device_details": {

            }
        }
    }
}

Auth Details

Param Description
request_details Object for all the request details. More details defined in the request details table.
response_details Object for all the response details. More details defined in the response details table.

Request Details

Param Description
date The date the auth request was made.
auth_profile_details The details of the auth_profile that was targeted. More details defined in the auth profile details table.
origin_location_data If location data was provided in the request, it is echoed here. More details defined in the location data table.
accepted_auth_methods The accepted auth methods for this request. If it was provided, these values are echoed back. If not provided, then all methods are echoed back with default rules. More details defined in the accepted auth methods table.

Auth Profile Details

Param Description
auth_profile_id Echo back the ID in the request.
nickname The nickname of the auth_profile record.
ref_id The ref id of the auth profile record.

Origin Location Data

Param Description
latitude Latitude location.
longitude Longitude location.

Accepted Auth Methods

Param Description
name The accepted method name.
rules The rules for the accepted auth method.

Response Details

Param Description
date The date the auth request was responded to.
auth_method The auth method that was used for the response. If there was a timeout, or declined, this will not be populated. More details defined in the auth method table.
secure_signed_message An object representing the signed object and cryptographic signature details. More details defined in the secure signed message table.
mobile_device_details The details of the mobile device that wasused to facilitate the auth. Even if the auth method was security key, there was still a mobile device where the app was installed. More details defined in the mobile devices details table.

Auth Method

Param Description
name The name of the auth method used.
usetype The way the auth method was used. Options for mobile device are: biometric or pin.

Secure Signed Message

Param Description
signed_data This is a base64 payload of the data that was signed for the auth request.
signature_data_details The data that is used to validate the signed data. More details defined in the signature data details table.

Signature Data Details

Param Description
hash_value The hashed value of the signed_data base64 data.
signature_data Dynamic JSON payload with signature data based on the auth method. More details below.
auth_method_usetype The way the auth method was used.
auth_method The auth method that was used to sign this data.
hash_method The hashing method of the base64 signed data.
signing_method How the message was signed.

Signature Data (security key)

Param Description
keyHandle The U2F KeyHandle that was used.
clientData The clientdata from the U2F security key.
signatureData The signature from the U2F security key.

Signature Data (mobile device)

Param Description
counter The counter value from the security key.
signature_value The base64 encoded signature value from the security key.
challenge The hash value from the base64 signed message. This is the value that is signed.
meta Data about the signature - mostly reserved for future use.
version The version of the signature data.
format The format of the signature data.
key_id The key id. Not used at this time

Signature Validation Details

Param Description
public_key The public key value used to validate the signature.
key_size The size of the public/private key.
key_type The type of key used. EC is the only key supported currently
signing_algorithm The type of hashing algorithm used to sign – the only possible value right now is SHA256.
curve_type The type of curve used if applicable.
key_format The format of the key, the only value right now is x.509.

Mobile Device Details

Param Description
platform The mobile platform that was used (Android or iOS).
model The model of the device.

Errors

The Auth Armor API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your Access token is not valid.
402 Request Payment -- Request for payment.
404 Not Found -- The specified auth profile does not exist.
405 Method Not Allowed -- You tried to access an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The auth profile requested has been removed from our servers.
415 Unsupported Media Type -- You requested a format that isn't json.
418 I'm a teapot.
429 Too Many Requests -- You're making too many requests!!! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.