OutSystems Platform allows you to customize the authentication logic to be used with REST APIs.

To implement it, take the following steps:

  1. Set the 'Authentication' property of the REST API to 'Custom'.
    This adds an OnAuthentication callback action to your REST API. It will be executed at every incoming request of this REST API, before the called method's action flow.
  2. In the OnAuthentication callback action, implement the logic to authenticate the client.
    If you need to access data received in the URL, header or body of the HTTP request, you can use the GetFormValue, GetRequestHeader and GetRequestContent actions of the HTTPRequestHandler extension.


We have an application to manage contacts. It has the 'Contacts' REST API with a method called 'GetContacts' that provides the list of all Contacts. To see how to create the REST API service and method, please read Expose Data using REST.
We want to use API keys to authenticate applications that send REST API requests to our server.

In this example we will implement a custom authentication logic, where the REST API expects to receive two parameters in the header: AppId and AppKey. These will be used to validate if the request is valid.

Set the REST API to Use Custom Authentication

We have to set the authentication mode for the REST API:

  1. Go to the Logic tab and expand the 'Integrations' folder;
  2. Select the 'Contacts' REST API. In the properties pane, set the 'Authentication' property to 'Custom'.

As a result, you have the 'OnAuthentication' callback action added to your REST API.

Implement Your Custom Logic

In the 'OnAuthentication' action flow, follow these steps to define the authentication logic:

  1. Use the GetRequestHeader action of the HTTPRequestHandler module to get the values of the parameters received in the request header. Learn how to add a reference to an action of another module;
  2. Use a user action to validate if the app id and the key is a valid API key;
  3. Add an If element that forks the action flow according to the result of the validation in step 3.
  4. On the branch where the API key is invalid, add a RaiseError element. In its 'Select Exception' dialogue, choose to create a new User Exception. Learn more about User Exceptions.
    Remember to add a meaningful error message to the exception. The message you set here will be displayed in the HTTP response if the authentication is not successful.

Test the REST API

After deploying to our environment in the public cloud, we test the method with a curl command:

curl https://osacademy.outsystemscloud.com/ContactsAPICustomAut/rest/Contacts/GetContacts

The result is a response with status code 500. The message body contains the error message you added when raising the User Exception:

Now let's test it with a valid app id and key that is stored in the APIKey entity:

curl -H "X-Contacts-AppId: ghjfxdfAvs596vcGfsvf0ef1" -H "X-Contacts-Key: 6tsdgdjl9fsKDd5zsvnwmdjosDmrufbs93susadLHDvjfhbnwtTRbsnucnrb" https://osacademy.outsystemscloud.com/ContactsAPICustomAut/rest/Contacts/GetContacts

The result is:

See Also

Add Basic Authentication | Expose Data using REST