Oct 21

 Token Based Authentication


The interaction between front-end and back-end for WaveMaker applications goes through REST APIs exposed by the back-end. For every service such as DB, Java, SOAP etc created/imported into WaveMaker application, the corresponding functionality is exposed through REST APIs. These REST APIs can be invoked from the application front-end or they can be integrated with other applications (non-WaveMaker applications). Invocation from the application front-end goes through the login page flow wherein a cookie is provided post authentication, which will be sent while invoking the back-end REST APIs.


If the REST APIs are invoked from a third-party application, the same login flow with cookie will not work. The other alternative is to send the credentials for each and every REST API call through Basic Authentication Header. Though this option works, it is not recommended for security reasons as every request carrying the credentials of the user. To avoid such problems, WaveMaker applications follows Token Based authentication mechanism for their REST APIs.

How it works

Token-based authentication is an authentication mechanism mostly used for authentication of API requests. In this mechanism, the user is issued an API access token upon successful authentication, which will be used while invoking any API request. In this process, a cookie will never be issued by the server. All requests are stateless.


What is a token?

A token is a piece of data created by the server containing information to uniquely identify the user. A new token is created for every token request, therefore there could be multiple tokens for the same user.

Eg: cc7112734bbde748b7708b0284233419.

The token should be sent as a Header with the name “wm_auth_token” when making API requests to the WaveMaker applications.

Token has a lifetime. It is valid for 1800 seconds from its creation(configurable). Expired tokens are not valid and will be discarded.

Token Repository

Tokens issued by the server are stored in the token repository. At present WaveMaker only supports In-Memory token repository, hence they will be lost if the server gets restarted.

Token Request

To obtain the Token an HTTP GET request has to be made to the following URL:  GET [app-hosted-url]/services/security/token by passing the credentials through Basic auth request. In Basic authentication approach, the credentials are encoded with Base64 and sent in the header with the name “Authorization” as shown below

Header as: Authorization : Basic <base64(username:password)>

Continuing with the above example, the service URL would be:
http://e1d52cdd8ecf.cloud.wavemakeronline.com/Demo/services/security/token and for username as admin and password as admin the header would be: Authorization : Basic YWRtaW46YWRtaW4=.

If your authentication credentials are correct, you will get the following message with the token: {"wm_auth_token":"ZXJpYy5saW46MTQ1ODE5MDcyNDU5NTpmZGQwYjUzMDNjMzRiZDgyZmUyZTBhZTQyYTM1NzJjYw"}

If user is not authenticated, you will get an error message as shown below along with the Http Response Code of 401: {"errors":{"error":[{"id":null,"messageKey":"com.wavemaker.studio.json$UnexpectedError","message":null,"parameters":["Require authentication to generate access token"]}]}}

Invoke API using Token

Once a token is issued, the APIs can be accessed, by passing the token as Header Or Param.
The following example shows to access the User table from the sample hrdb:
Token based authorization using header parameter:

Token based authorization using request parameter:


  • If token exists both as request parameter and header, then request parameter takes precedence. Though the token can be sent in either Header or Parameter, we recommend the Header approach for security reasons.
  • If the token is invalid, then 401 unauthorized error will be sent in response.

Token Validity

By default, a token is valid for 1800 seconds since its creation. You can customize token validity seconds in project-security-provider.xml by editing below bean, before deploying the app.

The API requests with an invalid/expired token will be returned with the 401 response code.

We use cookies to provide you with a better experience. By using our website you agree to the use of cookies as described in our Privacy Policy.