Here to help with using the AthenaMFA app and services

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.


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

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

email requiredEmail address to request approval from
useridIf 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.
ipaddressThe 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 optionalISO language code to send the one-time passcode email in if the user is not registered.

Request Approval (Response)

statusSee Status Codes (MfaAccountNotRegistered, MfaPushNotificationSent, MfaAuthenticateByCode,MfaEmailSent, ExpiredOrInvalidRequestId, TooManyRequests, Unauthorised)
emailEmail address of the user
mfarequestUnique ID for the approval request
mfarespondcodeThe 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

email requiredEmail address the push notification was sent to
mfarequest requiredThe 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 conditionalIf 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)

statusSee Status Codes (MfaPushNotificationSent, MfaAuthenticateByCode, MfaEmailSent, RequestDenied, RequestApproved, ExpiredOrInvalidRequestId, Unauthorised)

Response Status Codes

1000ExpiredOrInvalidRequestIdThe mfarequest parameter value has expired
2000MfaAccountNotRegisteredThe email address in the ApprovalRequest is not registered on the AthenaMFA platform
2001MfaPushNotificationSentThe approval request has been sent to the user via Push Notification
2002MfaAuthenticateByCodeThe user is required to respond to the Approval Request by code
2003MfaEmailSentThe user does not exist, MFA is mandatory and a one-time passcode has been sent via email
3000RequestResponseReceivedIntermediary status, the user has responded to the push notification, but it has not yet been verified.
3001RequestDeniedThe user has denied the request and the login should not be permitted.
3002RequestApprovedThe user has approved the request and the login should proceed.
3003TooManyRequestsWe limit the RequestApproval endpoint to 1000 requests per minute to prevent spamming, this can be increased by request.
3004UnauthorisedYour API key is not valid, or you are not allowed to make requests for the domain referer you have specified.


There are several packages available to assist with the integration with the AthenaMFA platform.


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

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

checkCallbackUrl requiredThe server side url to call which will invoke the REST API Check For Approval Response
successRedirectUrl conditionalThe URL to redirect the user to when they have successfully approved the login request
onSuccess conditionalFunction to invoke when the user has successfully approved the login request
failedRedirectUrl optionalThe URL to redirect the user to if the login request has been denied or it has expired.
onFail optionalFunction to invoke when the user denies a login request, or it has expired.
mfaRequiredIf 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.
showInfoIf 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
remindInDaysIf showInfo is true, this is the duration between reminders for the user register. Defaults to 7 days
timeoutThis is the period between automatically calling checkCallbackUrl in seconds. Defaults to 1 second
csrfTokenIf 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.
csrfHeaderNameIf 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

.NETInstall-Package AthenaMFA.Api.Integration
NodeJSnpm -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..