How-To Configure Postman for Crusoe REST API

Last Updated: Dec 24, 2025

Introduction

Postman is a popular API platform used by developers to design, build, test, and document APIs. It provides a user-friendly graphical interface (GUI) for interacting with APIs, making it easier to send requests, view responses, and debug issues.

In this article, we will walk through the steps required to configure Postman for use with the Crusoe Cloud API.

Prerequisites

• Active Crusoe Cloud account with access to a project

   

Step-by-Step Instructions

Step 1: Download OpenAPI Specification File

1. Navigate to the Crusoe Cloud Docs.
2. Go to Reference > API Reference.
3. Click on the link for the full API reference.
4. Click "Download" to download the OpenAPI specification file.
5. Right click and "Save as..." to your documents, downloads, etc., leaving the filename the default openapi.json.

Alternatively, copy the URL of the OpenAPI specification file and save it for the next steps.

Step 2: Download/Install Postman

1. Navigate to the Download Postman page on the official website.
2. Download the client according to your OS.
3. Install the client application.

Step 3: Import Collection

1. Open the Postman application.
2. In the Postman interface, navigate to your workspace and click the Import button.
3. Enter the URL of the OpenAPI specification file from earlier, or select the file which you downloaded.
   
4. Select "Import as Postman Collection" and click "Import".
   

Step 4.1: Configure Collection – Scripts

1. Navigate to the "Collections" tab in the Postman client.
2. Select the "Crusoe Cloud API Gateway" folder/collection.
3. Navigate to the "Scripts" > "Pre-request" tab.

4. Add the following script contents.

   const CryptoJS = require('crypto-js');
   const URL = require('url');
   
   const apiAccessKey = pm.variables.get("api_access_key");
   const apiSecretKey = pm.variables.get("api_secret_key");
   
   const signatureVersion = "1.0";
   
   const baseUrl = pm.variables.get('baseUrl');
   const requestPath = URL.parse(pm.request.url.toString().replace('{{baseUrl}}', baseUrl)).pathname
   const requestVerb = pm.request.method;
   
   const queryParams = pm.request.toJSON().url.query.filter((x)=>x.disabled!==true)
   
   let canonicalizedQueryParams = "";
   
   if (queryParams.length > 0) {
    canonicalizedQueryParams = queryParams
    .sort((a, b) => a.key.localeCompare(b.key))
    .map(param => `${param.key}=${param.value}`)
    .join('&') + "\n";
   }
   
   const dt = new Date().toISOString().replace(/\.\d{3}Z/, '+00:00')
   
   pm.request.headers.add({
    key: "X-Crusoe-Timestamp",
    value: `${dt}`
   });
   
   const payload = `${requestPath}\n${canonicalizedQueryParams}\n${requestVerb}\n${dt}\n`;
   
   try {
   const decodedKey = CryptoJS.enc.Base64.parse(apiSecretKey.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - apiSecretKey.length % 4) % 4));
   const hmac = CryptoJS.HmacSHA256(payload, decodedKey);
   const signature = CryptoJS.enc.Base64.stringify(hmac).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
   
    pm.request.headers.add({
    key: "Authorization",
    value: `Bearer ${signatureVersion}:${apiAccessKey}:${signature}`
    });
   
   } catch (err) {
    console.error("Error generating signature: ", err.message);
   }

5. Click "Save" to save changes.

Step 4.2: Configure Collection – Variables

1. Navigate to the "Variables" tab.
2. Ensure the following variables are present.

Note: the API Access Key and API Secret Key are obtained separately, see: https://docs.crusoecloud.com/identity-and-security/managing-api-keys

Step 5: Test the Collection

• Select a request in the Crusoe Cloud API Gateway collection, e.g.

GET {{baseUrl}}/projects/:project_id/compute/vms/instances/:vm_id

• Replace :project_id with your actual project ID.

• Replace :vm_id with the VM instance ID you want to query.

• Click on Run.

• Check the response:

  • Success: Status 200 OK and JSON data with details of the VM.

  • Failure:

    • 401 Unauthorized → check api_access_key and api_secret_key.

    • 404 Not Found → verify project_id and vm_id are correct.

• If the request succeeds, your collection is correctly configured and ready for use.