Skip to main content

mxHERO V3 API Key

Alex Panagides
Updated

The mxHERO V3 API lets your own scripts and systems manage datasets and S/MIME certificates without using the Admin Dashboard. This page explains how to create the API key, find your organization ID, and send your first authenticated request.

Before you begin

  • You need an Owner or Admin user in the Admin Dashboard (https://dashboard-v3.mxhero.com).
  • Decide where the key will be stored. Treat it like a password: anyone who has it can read and change your organization's datasets and S/MIME certificates.
  • The API covers two areas today:
    • Datasets API: read and update the key/value lists used by Auto Filing.
    • S/MIME API: upload certificates and assign them to email accounts.

How the API works

Item Value
Base URL https://api.mxhero.com/v3
Organization scope Every path starts with /organizations/{organizationId}/
Authentication Header x-api-key: <your key> on every request
Content type application/json for request and response bodies
Keys per organization One

Create the API key

  1. Sign in to the Admin Dashboard.

  2. Open Settings › Integrations.

  3. Select the Applications tab.

  4. Find the Integrate with mxHERO API card ("Manage your Datasets and S/MIME Certificates through an API.").

    The mxHERO API card on the Integrations Applications tab, showing the key actions and the help popover with the organization ID

  5. Click Create . The key appears on the card.

  6. Click the copy icon next to API Key and store the key in your secrets manager or password vault.

Find your organization ID

Use either of these:

  • On the Integrate with mxHERO API card, open the help popover. It shows Your Organization ID with a copy button.
  • Open Settings › Organization and domains. The organization name and ID are shown at the top.

The organization ID replaces {organizationId} in every request path.

Send a test request

Read one of your datasets. You need a dataset ID: open Auto Filling › Datasets, click Edit on a dataset, and copy the ID from the page URL.

curl -X GET "https://api.mxhero.com/v3/organizations/{organizationId}/datasets/{datasetId}" \
  -H "accept: application/json" \
  -H "x-api-key: {api-key}"

Replace {organizationId}, {datasetId} and {api-key} with your values. A working key returns the dataset as JSON. See Datasets API for the response format.

Manage the key

The card offers these actions:

Action Effect
Copy Copies the key to the clipboard.
Disable Stops all API access with this key until you enable it again. The dashboard asks you to confirm.
Enable Restores access for a disabled key.
Delete Removes the key permanently. Scripts that use it stop working.

To replace a key (for example, after a staff change or a suspected leak), delete it and create a new one, then update every script that uses it.

Warning: Never put the key in client-side code, a shared spreadsheet or a public code repository. If a key may have been exposed, disable it right away, then replace it.

Verify

  • The test request above returns HTTP 200 and your dataset.
  • The card shows the key as enabled.

Troubleshooting

Symptom Cause Fix
Request rejected as unauthorized or forbidden Key missing, mistyped, disabled or deleted Check the x-api-key header value. Make sure the key is enabled on the card.
404 for a dataset or certificate Wrong organization ID or object ID Copy the organization ID from the help popover and the dataset ID from the dataset's edit URL.
Requests worked, then stopped Key was disabled or deleted in the dashboard Check Settings › Integrations › Applications. User Activity shows who changed it.

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk