⛓️Authentication with custom backend

Authenticate your app users with your preferred backend tool

The Custom Authentication feature allows creating an authentication flow for your apps using any backend tool of your choice, even a custom backend.

In this page, we'll describe how to set up the design file and the necessary API requests to perform the user authentication.

What you will need

An app design with the Bravo authentication tags correctly set up.
A prepared backend with several endpoints for authentication: login, user information and (optionally) signup.
The API Collection configured in Bravo Studio.
Finally, bind the API requests to your UI elements to add functionality to your app.

Let's learn how to do all this!

If you don't have your user authentication backend ready, we suggest you to first follow our tutorial on how to set up Xano as your user authentication backend.

1. Setting up the UI

We'll need the following pages to set up the authentication flow in the apps:

Login page.
Signup page (optional).

🎨 Here is a sample Figma file with the setup:

The login page is displayed when the user is not logged in upon app startup or after logging out. It is important to note that only one login page can exist within the app. Components:

[page:login]: Add to the screen that we want to use as the login page.
[component:input-email]: Creates an input field for the account email.
[component:input-password]: Creates an input field for the account password.
[action:login]: Defines the action triggered by the button, facilitating the login process using the credentials entered in the previous fields.

You can either allow news users to register in your app or only allow access to a specific list of users defined in your backend. While this page is optional, it provides the simplest method for users to create their own accounts. Components:

[component:input-email]: Creates an input field for the account email.
[component:input-password]: Creates an input field for the account password.
[action:register]: This triggers the process of sending the filled information to the backend to create a new user account.

Log out action (optional)

If you want to provide an option for your users to log out after they have logged in, you can incorporate this action tag into a UI element. Component:

[action:logout]: This action enables the log out functionality and can be applied to any UI element within the app.

2. Creating the API collection and requests

Necessary API endpoints

After configuring the design file, the next step is to construct an API collection which contains all the essential requests for the authentication flow. This involves setting up the following endpoints in your backend tool:

A POST request for the login page
A POST request for the signup page (if applicable)
A GET request, called User Info, which retrieves user-specific information like user ID and username from the backend.

These endpoints must, at least, return the following data:

Login and signup actions (POST requests): The endpoint should return a user token value in the response message. This value is generated by the backend tool based on the authentication method used.
User Info request (GET request): The endpoint must return, at least, a user ID value. It can also return user name, user email and user picture values.

For comprehensive guidance on Setting up Xano as your user authentication backend, please refer to our dedicated tutorial: how to set up Xano as your user authentication backend.

Create the API collection in Bravo

Once we have the backend endpoints ready, we’ll create a new API collection in Bravo that will contain all the requests.

In Account Collections, click on Create a New Collection, and select Start from scratch.
Provide a Collection Name and if desired, Description and then, Save.
Click on the Collection Settings (look for the icon beside the collection name).
Navigate to the Authentication tab, indicate the authentication method that your backend uses.

Keep in mind that there are different authentication methods, it is important to identify which one your backend employs. Your backend may already have a specific method in place. For example, Xano utilises the bearer token method, issuing a JWT token upon successful user authentication. If you're unsure about the authentication method your backend employs, consult the tool or system's documentation for guidance.

For the Bearer token method, you must leave the Token value empty, as this will be later processed by Bravo to insert the correspondent for each specific user in the requests.

Add the requests to the API Collection

Let's define the individual API requests:

This request will be bound to the UI elements in the Login screen: the email and password input fields.

Create a new request in the collection, and select POST as the request type. Copy the endpoint URL from your backend tool, and paste it in the request URL.
Since it's a POST request, it's crucial to specify the body of the request, which will hold the email and password credentials. For this example, click Body and select JSON. If your backend uses a different format like Form-data, select that option instead.
Fill the body content with the following JSON:

{
  "email": "${email}",
  "password": "${password}"
}

Please note that ${email} and ${password} are Bravo variables designed to store values from the app's fields. On the other hand, the names "email" and "password" are the identifiers that the backend use to receive this data, so they must align with the API endpoint's definition. It's possible that they might differ, such as "_email" or "userEmail," for instance. It's important to verify the specific names required.

Time to test the login request! Make sure you have created a user in your user table. Go to Test Values and fill in the email and password variables with the values you have created:

Click Send, and you’ll get in the response from your backend. In the Received Data tab, select the parameter correspondent to the auth token:

Once selected, go to the Selected Data tab and set the Name as accessToken:

To make sure the request worked as expected, go to the Debug tab related to the request. If everything went well, you'll find the full user token value in the response message. Copy this value, as we’ll need it later to configure the User Info request.

If you've designed a signup page, you'll want a POST request to create new user accounts. Just like the login request, you'll first need to specify the API endpoint that handles adding new users in your backend tool.

Create a new request in the collection, and select POST as the request type.
Copy the endpoint URL from your backend tool, and paste it in the request URL.
Define a request body. In this case, the body will be the same we used for the Login request, but keep in mind that you’ll need to check the names for the keys (the ones to the left in the body) in your backend tool - "email" and "password" in this case.

Test the request providing some Test Values. If the request is successful, a new user with the specified email and password values will be created in the backend.
After clicking Send, based on you backend, you might receive a user token data which will allow the user to log in your app after sign in. If you wish to proceed with this, simply select the token data.
Just as the login request, once selected, go to the Selected Data tab and set the Name as accessToken:

User Info request (GET)

Let's set up a request to retrieve specific user information. This request must return a user ID as a unique identifier. Make sure this is properly configured in your backend tool. Additionally, it can also fetch data like the user's name, email, and profile picture.

Create a new API request and in this case, select GET as the request type.
Insert the corresponding endpoint URL.

It's important to note that this request will fetch data from a real user stored in your database. Therefore, it requires a valid user token for access. Otherwise, the access to the backend data will be unauthorised.

Go to the Test Values section, set _authorization as key name, and paste the user token you copied before from the Login/Signup request step before.

Test the request. If it’s successful, it will return the necessary user data specified before. You need to give these data items some specific naming in the Selected Data section:

User ID (mandatory): id
User name: name
User email: email
User picture: picture

In our example, we're only getting the "id" field, which is mandatory. If you get more data from your endpoint, use the names we've suggested.

All authenticated requests

An authenticated request means that the backend requires a valid authentication token to be included in the request headers when interacting with a specific API endpoint or group of endpoints. This allows the backend to process information tailored to the user who just logged into the app, like fetching a list of items or receiving user inputs through a form. The backend tool itself determines whether an endpoint requires authentication.

For example, the User Info GET request we set up earlier targets an authenticated endpoint in the backend, retrieving user-specific sensitive information. You'll likely want to add more authenticated requests to your API collection, which you can then link to different screens in your app.

By default, all requests in a Bravo API Collection are set to be authenticated, as long as this is specified in the Collection settings (which we did earlier here). o test them correctly, make sure to include the _authorization test value along with a valid token, as we did for the User Info GET request previously.

In case you get a 403 error after sending the test request, double-check that you've set the _authorization test value with a valid token. Also, ensure that the API collection has authentication enabled in the collection settings. You can obtain a new valid token by running a login request from the corresponding API request.

3. Binding the UI elements to the requests

For this part, you should have already set up the UI, imported the design to Bravo and created the API collection.

Go to your app's Integrations section and select the Custom Login option.
Select the GET User Info request created before. If everything is correct, you’ll see some green ticks next to the different user data items.

3. Make sure to click Save! Its time to bind the screens to the data items from the API requests.

Select the Login screen.
Bind the email and password inputs with the corresponding variables of the Login request body, as indicated below.

Then, in the Form Response Action section, select the Set Access Token option, and set the token variable to ${accessToken}. This is the name we gave to the data item containing the user token, in the Login request. This ensures that Bravo will securely store the user token upon successful login.

To define which is the app home page, you need to use the prototyping tool in your design. Don't use the "Go to page" action in the Form Response Action, otherwise the authentication setup won't work.

Finally, bind the signup screen (if applicable). Here you have two options: 1. Sign up and redirect the user to the Login screen. In this case, the user has to enter the log in credentials to finally access the app. To do this, set Go to page as Form Response Action and select the Login screen.