Discovering the Passbolt API using Postman: A beginner’s Guide

Most people who use passbolt are familiar with its user-friendly interfaces on the web and mobile. However not everyone is familiar with its underlying API. Using the Passbolt API is not that difficult and harnessing its full potential could open up a world of possibilities. In this guide, we'll explore how to get started with Passbolt API using Postman.

What are the benefits of using Passbolt API?

Automation: Passbolt API allows to automate repetitive tasks and integrate password management seamlessly into your existing workflow. For example if you're using automation to provision machines or configure services, or building something that requires a secret to be shared between two systems, the Passbolt API can help.

Customization: You can also leverage the API to tailor Passbolt to your specific needs. For example it is possible to create custom scripts to automate user provisioning, or to rotate secrets after a certain amount of time, whichever makes sense for your organization!

Scalability: For organizations with complex needs, Passbolt API facilitates scalability. You can better schedule or split time consuming tasks programmatically using the API.

What is an API?

An application programming interface (API) is a way for multiple computer programs to communicate with each other, such as the passbolt browser extension and the server, or the mobile application and the server. You can think of the API as a machine interface that allows applications to talk to each other in a structured and predictable fashion.

In the passbolt case, the data is exchanged using the JSON format, a lightweight text-based format for storing and transporting data. That format is quite popular as it is easy to parse and manipulate in the browser using JavaScript, as well as other popular programming languages.

The data exchange is done over HTTP(s), the ubiquitous protocol that is the foundation of the web. HTTP works in the form of requests and responses. These requests can represent different actions (also called methods) depending on what you want to do. For example a GET request will allow you to read information, a POST request will allow you to send data, for example when creating or updating a record, and a DELETE operation will allow you to delete a resource. 

Each request will warrant a response, which is categorized with response status codes. For example 200 OK represents a success, and 400 Bad Request represents an error. Most likely you’ve already come across the infamous 404 Not found error code when browsing the web, that’s just one of the possible error status codes.

Getting Started: Step-by-Step Guide

Step 1: Set Up Passbolt Instance

First of all you need to have a Passbolt instance up and running. For this guide it is best you install a dedicated test instance of Passbolt locally. You can follow the existing installation guides on the Passbolt website for detailed instructions.

Step 2: Obtain a temporary API authentication token

In order to browse user data using the API, authentication is required, just like when using the web interface. You can get one by logging in to your Passbolt instance using the console and going to the application directory, for example if you are using the packages this is typically located here:

cd /usr/share/php/passbolt
./bin/cake passbolt create_access_token --username=<youremail> --expiry="15 minutes"

You can then use the above command to generate a temporary API key to be used for authentication. This key will be used in Postman to authorize your requests.

As you can see this command takes two parameters, the username (or email) of the user you want to authenticate with, as well as the expiry, expressed as a duration in natural language or a date for example.

The output is what is known as a JSON Web Token (JWT). These are often used in web based applications for temporary authentication. Think of it as a signed data package that carries information about the user in a compact format. Once decoded the core data (or payload) will look something like this:

{
  "iss": "https://my-passbolt.domain.com",
  "sub": "f848277c-5398-58f8-a82a-72397af2d450",
  "exp": 1705423221
}

The first parameter iss stands for the issuer, the domain that generated such a token. The sub corresponds to the subject, e.g. the user id in passbolt expressed as a UUID. The exp stands for expiry, e.g. the time after which the token will not be valid anymore, expressed as Unix time (time elapsed since 1 January 1970).

Of course you can also generate such a key by performing a login operation using the API, but this is a bit more complicated, and would warrant a separate tutorial. Similarly, for simplicity's sake, we won’t cover the process related to the multi-factor authentication, we’ll just assume you’re using a user that doesn’t have it enabled.

Step 3: Install Postman

If you haven't already, download and install Postman from the official website. You can also use an open source alternative like Insomnia. Both are versatile API testing tools that simplify the process of sending requests over HTTPS and viewing the results.

Step 4: Configure Postman authentication

You can then start by creating a new blank personal workspace and a new collection. The collections will allow to group the requests, like a folder for files. Select that new collection “Authorization” tab, and set the authorization method to “Type: Bearer Token” and place the previously generated JWT in the “Token” field. This will allow you to avoid having to share a common authentication method for every request under the collection, and easily replace the token once it expires.

Step 5: Create a request to fetch resources

It is now time to create our first request. With this one we will list all of the resources present in passbolt for the user. You can let the default request type (GET) and enter the Passbolt API url `https://[yourdomain]/resources.json` . Then under authorization, make sure “Inherit auth from parent” is selected. Then you can click send and voila! Under the body you can see the response from the API.

The API returns data in an envelope with “header” and “body” properties. The “header” contains response metadata like response code, server_time, error messages etc. The “body” contains the actual data.

Step 6: Explore Passbolt API Endpoints

You can nowt continue to explore the API by referring to the Passbolt API documentation to understand available endpoints and their functionalities. The documentation provides detailed information on API endpoints, request/response formats, and examples, ensuring you have the necessary guidance as you implement advanced features.

Continue to experiment with different requests in Postman to interact with Passbolt programmatically, you will rapidly see some patterns emerge and it will become easier and easier.

Moving Forward: Documentation Resources

In conclusion, utilizing Passbolt API with Postman opens doors to enhanced password management, automation, and scalability. By following this guide, you've taken the first steps towards unlocking the full potential of Passbolt, and with the comprehensive documentation available, you're now equipped to explore advanced functionalities and tailor Passbolt to your specific needs.

Feel free to reach out on the community forum if you have questions or need help with a specific endpoint or request. Similarly if you liked this article and would like to see more, feel free to suggest a topic for the next tutorial. What should we do next?