How to authenticate to Baserow using database and JSON web tokens

• Prerequisites
• Baserow authentication
• Understand Baserow token types
  • Database token
  • JSON Web Token (JWT)
  • When to use Baserow tokens
• Practical examples of token use
  • Example 1: Access book data using the database token
  • Example 2: Import a template using the JSON web token (JWT)
• Conclusion

Authentication plays an important role in every application. It’s all about making sure users can access the platform securely while keeping sensitive data secure.

In this article, we’ll provide an overview of Baserow authentication, token types, and practical examples to help you understand Baserow’s authentication mechanisms. We’ll cover the differences between these tokens, when to use each, and how to set them up securely.

Prerequisites

To follow this article, you’ll need the following:

• A Baserow hosted or self-hosted account.
• Familiarity with Baserow’s features and capabilities.
• Knowledge of application programming interface (API) concepts.

Baserow authentication

Baserow’s authentication is all about protecting data stored in Baserow and ensuring that only authorized users can access and interact with the database and its data. It’s like having a locked door on your database to keep out unauthorized users.

To access Baserow securely, you need to verify your identity by providing a username and password or using other secure methods like tokens. This reduces the risk of unauthorized access. Once authenticated, you can view or modify data based on your assigned permissions. For more information on permissions, see the permissions overview.

Understand Baserow token types

Baserow offers two types of tokens for authentication, each used for specific tasks:

• Database token
• JSON Web Token (JWT)

These tokens have different capabilities in terms of API interactions.

Usually, we have API keys that are meant to be

• on the client-side (VueJS, React, vanilla JS, etc.).
• on the server-side only (NodeJS, Rails, Django, Go, etc.).

Let’s explore the differences between these tokens and how to use them securely to protect your Baserow instance.

1. Database token

Database tokens are primarily used for authenticating external applications or services to interact with Baserow’s databases.

The database token can be easily generated from the Dashboard → User settings → Database tokens → Create token.

This token serves specific purposes:

• Client-side usage: It’s suitable for use on the client-side of your application, where it can be safely exposed. Technologies like VueJS, React, or vanilla JavaScript can make use of this token.
• Self-documented API access: The database token grants access to the database API documentation. This API provides comprehensive documentation making it easy to fetch data using endpoints like http://localhost/api/database/rows/table/386/?user_field_names=true. If you’re using Baserow Hosted, the URL will be different, such as https://api.baserow.io/api/....
• No expiry: The database token never expires by default, but you have the flexibility to edit its create, read, update, delete (CRUD) rights as needed.

Be careful not to expose your token information, especially in public repositories, for security reasons.

2. JSON Web Token (JWT)

JSON web tokens (JWTs) are primarily used for user authentication within Baserow itself.

The JWT has more robust capabilities and is obtained by sending a POST request to http://localhost/api/user/token-auth/ with your username and password created during your initial project setup.

Here’s what it enables:

• OpenAPI specification: With the JWT, you gain access to Baserow’s full spec API, available on Redoc. This includes functionalities like user invitations, adding people to your workspace, and changing passwords. The API documentation can be found at https://api.baserow.io/api/redoc/.
• Two-part token: The JWT consists of two parts:
  • JSON web token access: This token expires every 10 to 15 minutes and is used to perform API operations.
  • JSON web token refresh period: The refresh token has a longer expiry, typically every 7 days. It automatically updates the JWT access period when it expires, without the need for users to re-authenticate with their email and password.
• Customizable duration: If you’re self-hosting Baserow, you can customize the duration of both the JWT access period and refresh token to align with your security preferences.

When to use Baserow tokens

Knowing when to use each token type is important:

• Use database tokens when you need to integrate external systems or applications with Baserow’s databases securely, and when you’re dealing with specific database actions, like querying data.
• Use JWTs when you want to authenticate and manage user access to Baserow’s web interface or when making authenticated API requests as a user, and when you want to access Baserow as a whole, like logging in, navigating around, or doing different tasks within Baserow.

There are fewer actions you can perform with the REST API using database tokens. Only a subset of endpoints is compatible with database tokens when compared to JWT authentication.

You don’t get as many granular rules with database tokens, just their CRUD access. So we recommend that users on the Advanced or Enterprise plan who want to use RBAC levels of granularity should use JWTs rather than database tokens.

Practical examples of token use

With all of this in mind, let’s explore two practical use cases to understand how these tokens are used in real scenarios. These examples will show how to leverage the appropriate token for different scenarios, to ensure both security and functionality.

Example 1: Access book data using the database token

Let’s say we want to access data from the Book Catalog template on Baserow.

In this case, we’d use the database token to make API calls to fetch data. With this, we can iterate over the book collection, extract details like titles and cover images, and display them in a custom application.

Remember to keep sensitive tokens secure and avoid exposing them in your frontend code or public repositories.

Here’s how we can do it using the database token:

1. Get the database token from your Baserow settings page or make HTTP calls using tools like Insomnia or Postman.

   

   After setting up tokens and authentication, you can proceed to access and manipulate data within your Baserow instance.

2. You can choose your preferred frontend framework, including VueJS, React, or even Vanilla JS, to create a user interface and interact with the API. Proceed with some VueJS code or any other framework that you like.

3. Assuming that you have one of the LTS versions of Node.js, you can run the following command in your terminal:

   $ npm init vue@latest
   

4. Follow the interactive steps to set up your VueJS project. Make sure to include vue-router for easier navigation, so check YES for that one! ✅

5. Install the necessary dependencies with NPM, yarn, or PNPM and proceed with a dev script start:

   

   There is already a /src/router/index.js defined for us in the scaffolded project.

   We can update it or aim directly towards /src/views/HomeView.vue and edit the file right there (the one used for the / URL).

6. At the root of the project, we then need to create an .env file based on the .env.example (you can rename it if you want). Then, populate the VITE_BASEROW_DATABASE_TOKEN field. The name can be as you’d like but since Vue3 projects are using Vite as a bundler, you’ll at least need to prefix it with VITE_ so that it is exposed properly to our frontend. More details can be found here.

   ⚠️ Remember to leave your .env file out of Git, and avoid committing it to version control for security reasons but rather using env variables (locally or in production).

7. We will then use [useFetch](https://vueuse.org/core/useFetch/#usefetch) from VueUse, a popular VueJS composables library to handle the HTTP calls. Here is the exact code snippet for the call.

In the file, we mainly have a bit of markup to cycle through the collection of books, some imports + environment variables, and the API call to fetch the given books.

As you can guess:

• VITE_BASEROW_DATABASE_TOKEN is the database token that we just copied from Baserow’s settings modal
• VITE_BASEROW_BASE_URL is the base URL for all the calls, useful if you want to toggle between a local version (e.g.: using Docker) or a self-hosted/cloud version of Baserow.

Now, let’s proceed to a bit of Composition API and styling.

Import the Book Catalog template successfully.

Note that if you import a different template, the markup that we have right now is not guaranteed to work. The structure of the response may be a bit different. Refer to the API documentation to get an example of what to pass/expect to receive. It’s dynamic and based on what is already installed, it can be quite helpful to speed things up!

Get the table ID. The ID of the table is the one that you can find after the table part in the URL. 821 in the screenshot below. This can vary on your side, of course.

If we inspect the HTTP call, we can see the authorization token publicly, which is totally fine, and a list of 12 books. This is the default number of books in the Book Catalog template:

That is aimed toward your instance of Baserow and creating a database token from your user settings page. This is how it looks on Excalidraw:

We have integrated our public database token with an existing database. Now, let’s explore how we can import a template.

Example 2: Import a template using the JSON web token (JWT)

Let’s say we want to import this Book Catalog template into Baserow programmatically.

We’ll need to use our JWT through a proxy so that we can keep the entire interaction with the Baserow instance private. Remember: we should not expose this on the front-end.

⚠️  We need to use a proxy because the JWT that we’ll be using cannot be used on the front-end directly. This token allows for more powerful operations that could be dangerous if used in a frontend-only environment (password reset, user management, etc.).

We will follow these steps:

1. Use a proxy server, such as a 24/7 running VPS server (e.g., DigitalOcean, Linode), a serverless cloud function (e.g., Supabase, Vercel), or a meta-framework (e.g., NextJS or NuxtJS) to send the query to install the template. Basically, the proxy can be any kind of backend in between our Baserow instance and our Web UI frontend. In our case, we’ll import using a serverless function from Netlify as a proxy, but it can be done with any backend as mentioned.
2. Create an account on Netlify and configure the Netlify CLI for a smoother setup in the future.
3. Create a proxy using Netlify serverless functions or another backend solution. This proxy will handle the JWT, ensuring that the interaction with the Baserow instance remains private and secure.
4. Send the query to install the template using the JWT via the proxy server. For example, use this endpoint: https://api.baserow.io/api/redoc/#tag/Templates/operation/install_template_async.
5. Implement polling to track the progress of the template installation, so that we can monitor the installation progress in real-time and we know when the template is done installing. As this process may take some time, it’s nice to know the progress in real-time.

So, install the package + netlify login + click the confirmation window in your browser. Keep the JWT private and use it to interact with your Baserow instance securely.

By using this approach, you can securely import templates into your Baserow instance without exposing sensitive tokens on the front-end.

This is how it looks on Excalidraw:

Conclusion

Understanding Baserow’s authentication tokens is essential for building secure and functional applications. We covered how different they are, which one you may need, and how to set them up properly so that you will never experience anything malicious.

To make the most of Baserow and keep your data safe, it’s essential to know when to use a database token and when to use a JSON web token (JWT). These tokens help you automate tasks or build apps with Baserow to meet your specific needs while maintaining security. By using the right token for each scenario and following best practices for token management, you can harness the power of Baserow while ensuring the safety of your data and user information. Only authenticated users with the appropriate permissions can view or modify data.

Remember to refer to the database API documentation for specific endpoints based on your project’s needs. The OpenAPI docs can be found here at https://api.baserow.io/api/redoc/ or if you are looking for the OpenAPI schema here https://api.baserow.io/api/schema.json.

Other useful resources

The following articles may also be helpful:

• Create a Baserow plugin for language translation with ChatGPT
• API integration: How to upload a file to Baserow using multipart/form-data
• API integration: How to upload files via URL
• Simplify your workflow: Automate with Baserow batch API calls

If you have any questions while following this article, feel free to ask for help in the Baserow community.