API guide

Give an integration the access it needs

Connect an order system or server process to RouteIQ with a named API key. Choose the permissions it needs, test the connection, and keep a clear way to replace or remove its access.

Updated October 23, 2026
Use one key for one identifiable integration. A name such as “Order system — staging” makes it easier to find the right connection when an environment changes or access needs to stop.

Choose the connection and role

Use a server API key when your own backend or automation needs to call RouteIQ's API. If you are setting up a supported map, SMS, email, or payment provider, start with Integrations. To receive changes from RouteIQ, use webhooks alongside the API.

An API key acts with the permissions of its selected Service Role. Choose the lowest role that can carry out the intended workflow. For an order system that creates and dispatches jobs, start by checking the Dispatcher role against the endpoints you need.

You need an administrator account to create and manage keys. Available roles depend on your own permissions. The selected service role cannot be changed after creation; create a replacement key if the required role changes.

Keep test and production connections separate, and confirm the selected site before creating a key. Record the integration owner, environment, and purpose in your team's credential inventory.

Create and save the key

  1. Open Settings → API Keys and select Create API Key.
  2. Enter a recognizable Name, such as “Order system — staging.”
  3. Choose the Service Role and add a Description explaining what uses the key.
  4. Select Create API Key.
  5. In Save your API key, select Copy and store the value in your server's secret store or password manager.
  6. Confirm I've saved my key only after it is safely stored.
The full value is shown once.

The list displays a redacted key for identification. You cannot reopen it to retrieve the secret. Keep the key out of browser code, mobile apps, repository files, screenshots, and ordinary support messages.

Verify the connection

  1. Configure the integration with the correct site's API base URL and the new key in the x-api-key request header.
  2. Make an authorized read request for a known test record. Confirm it returns the record from the intended site.
  3. Test the specific operations the integration needs using test work. A successful read does not prove permission to create, assign, or cancel jobs.
  4. Confirm the integration handles permission failures without retrying them as if they were temporary network errors.

Use the API reference for the current request contracts and the dispatch API guide for a job workflow. For example, the read route for an existing job is GET /job/{id} under the site's API base URL.

Replace a key without losing track of access

For a planned change, create a second named key with the required role, update the integration to use it, and verify the new connection. Once all consumers use the replacement, revoke the old key.

Use Regenerate when you intend to replace a key on its existing record:

  1. Find the integration in Settings → API Keys and select its Regenerate action.
  2. Read and confirm the warning. The previous key stops working immediately.
  3. Copy the replacement from Save your API key, update every service using that key, and run the verification again.

There is no overlap period when you regenerate. If you lost the original secret, it cannot be recovered from the Dashboard. Replace it and update the integration.

Remove access that is no longer needed

  1. Find the key by its name and description.
  2. Open its Actions menu and choose Revoke.
  3. Confirm only when you intend to stop every integration using that key. Revocation takes effect immediately and cannot be undone.
  4. Remove the retired value from the integration's configuration and verify it is no longer making successful requests.

If a key was exposed, remove its access promptly and issue a new key to the intended integration. Renaming a configuration elsewhere does not invalidate a credential.

Troubleshooting

I cannot find API Keys or create a key

Use an administrator account for the correct site. The role choices are limited by the permissions of the account creating the key.

The key worked before and now fails

Check whether it was regenerated or revoked and whether the integration still uses the retired value. Also check the site's API URL and whether the header is being sent.

The API rejects an action

Confirm that the key's service role is permitted to perform that action and access that record. If its role needs to change, create and test a replacement key with the appropriate role.

I only have the redacted value from the table

The redacted display is not an authentication credential. Use the value stored when the key was created, or replace the key if it was not saved.

For a connected AI client, also see Connect AI agents to RouteIQ.