Getting Started
Before you begin, if you have not already done so, ensure you have followed the Portal User Guide to create your free account and have registered your first application.
REST API
We recommend that all REST API calls are made server side to protect your Secret API key.
All requests must contain the HTTP Header Authorization: Bearer {{your secret API key}} where the API key is the API key from the application you have created in the AthenaMFA Portal.
All requests must also contain the HTTP Header referer, this is the domain (including protocol) where the request is coming from, it must match a domain added to the application your secret key is associated with.
To start the approval process first make a call to the RequestApproval endpoint, followed by either CheckForApprovalResponse if the approval request was sent via push notification or ValidateRespondCode if the user has been prompted to respond by code.
The base address for all API calls is https://api.athenamfa.com
Request Approval (Request)
Request approval for a login to an application.
Push notifications must be responded to by the user within 30 seconds of being sent or it will revert to respond by code, respond by code requests must be actioned by the user within 90 seconds. If either of these periods are exceed the request will be denied.
The first time a user an approval request is made for an application they will always be required to respond by code, they can then choose to have future requests sent via Push Notification.
POST /authentication/v1/requestapproval
| Parameter | Description |
|---|---|
| email required | Email address to request approval from |
| userid | If the user logs in with a username different to their email address, you can optionally send their user id they logged in with. This will be displayed on the push notification prompt. |
| respondonly | (true/false) Default: false. Will try to send a push notification if the user has agreed to receive them. If this to true, the user will always need to response with a code from the AthenaMFA application. |
| ipaddress | The client IP address of the user requesting approval, we use this to lookup the location of the user for information purposes only. |
| mandatory | (true/false) Default: false. If set to true and the user is not a registered AthenaMFA user, an email will be sent with a one-time passcode, this is valid for 10 minutes. |
| language optional | ISO language code to send the one-time passcode email in if the user is not registered. |
Request Approval (Response)
| Parameter | Description |
|---|---|
| status | See Status Codes (MfaAccountNotRegistered, MfaPushNotificationSent, MfaAuthenticateByCode,MfaEmailSent, ExpiredOrInvalidRequestId, TooManyRequests, Unauthorised) |
| Email address of the user | |
| mfarequest | Unique ID for the approval request |
| mfarespondcode | The request id which the user must respond to if prompted to respond by code |
Validate Approval Response (Request)
If the Request Approval returned a status of MfaPushNotificationSent, the user will have 30 seconds to respond to the Push Notification, poll this endpoint to check if the user has responded to the Push Notification request.
If the Request Approval or Validate Approval Response returned a status MfaAuthenticateByCode or MfaEmailSent, the user is required to either respond with a code from the AthenaMFA mobile application (MfaAuthenticateByCode) or the one-time passcode from the email (MfaEmailSent).
POST /authentication/v1/validateapprovalresponse
| Parameter | Description |
|---|---|
| email required | Email address the push notification was sent to |
| mfarequest required | The mfarequest from the Request Approval Response |
| allowfuturepush conditional | (true/false) If the user is required to respond to a code and the user has opted to have future approval requests sent via Push Notification |
| allowservicenotifications conditional | (true/false) If the user is required to respond to a code and the user has agreed to allow you application to send other push notifications (reserved for future use) |
| otpcode conditional | If the user is required to respond to a code or they have been sent a one-time passcode email, this is mandatory and is the response code they enter. |
Validate Approval Response (Response)
| Parameter | Description |
|---|---|
| status | See Status Codes (MfaPushNotificationSent, MfaAuthenticateByCode, MfaEmailSent, RequestDenied, RequestApproved, ExpiredOrInvalidRequestId, Unauthorised) |
Response Status Codes
| Code | Text | Description |
|---|---|---|
| 1000 | ExpiredOrInvalidRequestId | The mfarequest parameter value has expired |
| 2000 | MfaAccountNotRegistered | The email address in the ApprovalRequest is not registered on the AthenaMFA platform |
| 2001 | MfaPushNotificationSent | The approval request has been sent to the user via Push Notification |
| 2002 | MfaAuthenticateByCode | The user is required to respond to the Approval Request by code |
| 2003 | MfaEmailSent | The user does not exist, MFA is mandatory and a one-time passcode has been sent via email |
| 3000 | RequestResponseReceived | Intermediary status, the user has responded to the push notification, but it has not yet been verified. |
| 3001 | RequestDenied | The user has denied the request and the login should not be permitted. |
| 3002 | RequestApproved | The user has approved the request and the login should proceed. |
| 3003 | TooManyRequests | We limit the RequestApproval endpoint to 1000 requests per minute to prevent spamming, this can be increased by request. |
| 3004 | Unauthorised | Your API key is not valid, or you are not allowed to make requests for the domain referer you have specified. |
Packages
There are several packages available to assist with the integration with the AthenaMFA platform.
JavaScript
For web applications there is a javascript package to manage the responses from the API and present the user with the prompts to complete the authentication and approval process.
This is available from JSDelivr https://www.jsdelivr.com/package/npm/athenamfa
Simply add the script tag for the athenamfa.js file and the link tag for the athenamfa.css.
Initialise the library by invoking AthenaMfa.Init(options)
For example AthenaMfa.Init({checkCallbackUrl: '/validateresponse',successRedirectUrl: '/Home/Welcome',showInfo: true})
Initialisation options
| Parameter | Description |
|---|---|
| checkCallbackUrl required | The server side url to call which will invoke the REST API Check For Approval Response |
| successRedirectUrl conditional | The URL to redirect the user to when they have successfully approved the login request |
| onSuccess conditional | Function to invoke when the user has successfully approved the login request |
| failedRedirectUrl optional | The URL to redirect the user to if the login request has been denied or it has expired. |
| onFail optional | Function to invoke when the user denies a login request, or it has expired. |
| mfaRequired | If users are required to use MFA and they are not registered on the AthenaMFA, display a prompt with instructions to get started. Defaults to false. |
| showInfo | If the user is not registered but it is not mandatory, this will display a dialog with benefits of mfa and a guide to getting started. They can choose to remind them later. Defaults true |
| remindInDays | If showInfo is true, this is the duration between reminders for the user register. Defaults to 7 days |
| timeout | This is the period between automatically calling checkCallbackUrl in seconds. Defaults to 1 second |
| csrfToken | If the endpoints for checkCallbackUrl and validateRepsonseCodeUrl use antiforgery tokens to prevent cross site scripting, this is the csrf token that should be sent with requests. |
| csrfHeaderName | If the endpoints for checkCallbackUrl and validateRepsonseCodeUrl use antiforgery tokens to prevent cross site scripting, this is the header name which includes the csrfToken, by default it is sent for common headers RequestVerificationToken, xsrf-token, csrf-token, x-xsrf-token and x-csrf-token but you can override if you use custom header for this value. |
NOTE: either successRedirectUrl or onSuccess must be supplied.
To display the AthenaMFA prompt, pass the result from the server-side call to the requestapproval endpoint to the function as AthenaMfa.ValidateMfa(data)
REST API Wrapper Libraries
There are packages for many platforms to allow quick integration with the AthenaMFA REST API’s
| Platform | Installation |
|---|---|
| .NET | Install-Package AthenaMFA.Api.Integration |
| NUGET | AthenaMFA.Api.Integration |
| NodeJS | npm -i athenamfa-api-integration |
Example Projects
There are several example basic implementations available from our public github repository
Happy coding and lets secure our applications by default..