Skip to main content

Getting Started

This guide walks you through everything you need to start working with the MaintainX® REST API: generating an API key, setting up an API client, and sending your first request. By the end, you'll have a working setup you can use to explore and integrate with MaintainX.

Generate a MaintainX API Key​

To use the MaintainX REST API, you first need to generate an API key. The key is used to authenticate you so you can send requests to the MaintainX REST API via a bearer token.

  1. From the sidebar, select Settings, and under Organization Settings, select Integrations.

  2. On the Integrations page, select API Keys to display the API Keys options.

  3. Select + New Key.

    The Generate a New API key dialog opens.

  4. Enter a label for your key. Choose a name that indicates what the key is for.

  5. If you see a Key usage field, select REST API.

  6. If your plan includes multiple organizations, and you want to use the REST API to connect to more than one of them, toggle the Allow this token to be used on all my organizations option on.

    For more information, see API Key Organization Scope

  7. Select Generate Key. A confirmation dialog with your key opens.

  8. From the confirmation dialog, select Copy Key to copy the key to the clipboard.

    warning

    MaintainX only displays the key the first time you generate it. If you don't copy the key, you can't display it again later. However, you can always generate a new key.

API Key Organization Scope​

When you generate a new API key, the Allow this token to be used on all my organizations controls whether or not you can use the key to access more than one of your MaintainX organizations.

Turn it off to scope the key to your current organization. Turn it on to create a multi-organization key that can act on several organizations.

If you enable it, you'll need to identify the target organization with a header when you make requests. For details, see Multi-Organization Token.

Test Your API Requests​

After you create an API key, test it to make sure you can connect to your organizations.

These instructions assume you're using the open source Bruno API client. You can use another client (e.g., Insomnia), but the setup steps will vary.

Install Bruno​

If you haven't done so already, download the Bruno application from the web, and install it.

Create an Environment​

Create an environment to hold the variables you'll reuse across requests.

  1. Open Bruno, and make sure you're on your workspace's home screen.

  2. Select the Environments tab, then select + to create a new environment.

  3. Name the new environment MaintainX.

  4. Add two variables to this environment:

    NameValue
    baseUrlhttps://api.getmaintainx.com/v1
    bearerToken{GENERATED_KEY}

    This is the API key you generated in MaintainX.

    If you haven't generated a key yet, or forgot to save it somewhere, you can generate a new one.

  5. In the bearerToken row, toggle the Secret toggle on so your key is masked and kept out of any files you share or commit.

  6. Select Save to save the environment.

Import the MaintainX API Collection​

  1. In Bruno, select + from the Collections sidebar.

  2. Select Import collection. The Import Collection dialog opens.

  3. On the URL tab, paste the following into the URL field.

    https://api.getmaintainx.com/v1/openapi.json

  4. Select Import. The Import Collection dialog opens.

    Make sure the values are set as follows:

    FieldValue
    LocationLeave the default value
    File formatOpenCollection (YAML)
    Folder ArrangementTags

  5. Select Import.

You should now see a new collection named MaintainX API with all the MaintainX REST API endpoints.

Add Your API Key as the Bearer Token​

  1. In the Collections sidebar, right click the MaintainX API collection, then select Settings.

  2. On the Auth tab, enter the following in the Bearer Token field:

    {{bearerToken}}

    This is the variable you created earlier. The requests inside the collection will inherit this API key authentication.

  3. Select Save.

Test your Bruno configuration​

You should now be set up to make requests to the MaintainX API. To validate your setup, send a test request. If you encounter any issues, contact MaintainX Support.

  1. Expand the MaintainX API collection, then expand the Locations folder.

  2. Select the List locations endpoint.

  3. On the GET List Locations tab section, make sure the address bar has only the following:

    {{baseUrl}}/locations

  4. Select the Headers tab for the request.

  5. Do one of the following:

    • If your API key is scoped to a single organization, clear the checkboxes for the x-organization-id and x-organization-ids headers.

    • If your API key is a multi-organization key, select the x-organization-id header to identify the organization, or x-organization-ids header to identify several organizations at once.

      warning

      The x-organization-id and x-organization-ids headers are mutually exclusive, and are only needed if your API key is multi-organization. See Multi-Organization Token for details.

  6. Select Send.

  7. In the Response section, you should see the JSON response containing your organization's locations.