API Authentication (TrackServiceKey)

Q: How do I authenticate TrackRoad REST API calls?

Send your TrackServiceKey in the X-API-Key header on every REST request.

Q: How do I authenticate TrackRoad SOAP calls?

For SOAP, send your TrackServiceKey in SessionIDHeader as SessionID on each SOAP request.

Q: Do I need Login/Logout?

No. Login/Logout endpoints are legacy. New integrations should use TrackServiceKey authentication.

Q: Why do I get 401 Unauthorized?

Common causes include a missing X-API-Key header, an invalid key, extra whitespace, or using the wrong environment or host.

TrackRoad APIs use an API key called TrackServiceKey. For REST, send it as X-API-Key. For SOAP, send it in SessionIDHeader as SessionID.

Authentication overview: TrackServiceKey is your API key — send it as X-API-Key for REST and as SessionIDHeader/SessionID for SOAP.

Need endpoints and models?

Swagger provides the full request and response schemas for Dispatch, Routes, Route, Geocode, Credit, and Distance.

View Swagger UI API Reference Overview

How authentication works
Generate your TrackServiceKey
REST authentication (X-API-Key)
SOAP authentication (SessionIDHeader)
Login / Logout (legacy)
Security best practices
Common errors (401/403)
Related endpoints
FAQ

How authentication works#

TrackRoad uses a single authentication concept across its API surface: your account-level TrackServiceKey.

TrackServiceKey is generated in your TrackRoad account.
REST: send it in X-API-Key on every request.
SOAP: send it in SessionIDHeader as SessionID on every call.

Recommended for new integrations: use REST wherever possible and keep SOAP only for legacy systems.

Generate your TrackServiceKey#

Before calling the TrackRoad API, create or copy your authentication key from your account.

Sign in to your TrackRoad account.
Open Manage Users (or API settings, if available).
Generate or copy your TrackServiceKey.
Store it securely on the server side only.

If you cannot find your TrackServiceKey, contact TrackRoad Support to enable or confirm API access.

REST authentication (X-API-Key)#

Send your TrackServiceKey in the X-API-Key header on every REST request to TrackRoad.

curl -X POST "https://trackservice.trackroad.com/rest/credit" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY"

using System.Net.Http;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", "YOUR_TRACKSERVICEKEY");

var resp = await http.PostAsync("https://trackservice.trackroad.com/rest/credit", null);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

const res = await fetch("https://trackservice.trackroad.com/rest/credit", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_TRACKSERVICEKEY" }
});
console.log(await res.text());

import okhttp3.*;

public class Main {
  public static void main(String[] args) throws Exception {
    OkHttpClient client = new OkHttpClient();

    Request request = new Request.Builder()
      .url("https://trackservice.trackroad.com/rest/credit")
      .post(RequestBody.create(new byte[0], null))
      .addHeader("X-API-Key", "YOUR_TRACKSERVICEKEY")
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

import requests

url = "https://trackservice.trackroad.com/rest/credit"
headers = { "X-API-Key": "YOUR_TRACKSERVICEKEY" }

r = requests.post(url, headers=headers)
print(r.text)

<?php
$ch = curl_init("https://trackservice.trackroad.com/rest/credit");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_TRACKSERVICEKEY"]
]);
echo curl_exec($ch);
curl_close($ch);

require "net/http"

uri = URI("https://trackservice.trackroad.com/rest/credit")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri)
req["X-API-Key"] = "YOUR_TRACKSERVICEKEY"

res = http.request(req)
puts res.body

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://trackservice.trackroad.com/rest/credit", nil)
  req.Header.Set("X-API-Key", "YOUR_TRACKSERVICEKEY")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

fun main() {
  val client = HttpClient.newHttpClient()
  val req = HttpRequest.newBuilder()
    .uri(URI.create("https://trackservice.trackroad.com/rest/credit"))
    .header("X-API-Key", "YOUR_TRACKSERVICEKEY")
    .POST(HttpRequest.BodyPublishers.noBody())
    .build()

  val resp = client.send(req, HttpResponse.BodyHandlers.ofString())
  println(resp.body())
}

#include <curl/curl.h>

int main(void) {
  CURL* curl = curl_easy_init();
  if(!curl) return 1;

  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "X-API-Key: YOUR_TRACKSERVICEKEY");

  curl_easy_setopt(curl, CURLOPT_URL, "https://trackservice.trackroad.com/rest/credit");
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POST, 1L);

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);
  return (res == CURLE_OK) ? 0 : 1;
}

#include <curl/curl.h>

int main() {
  CURL* curl = curl_easy_init();
  if(!curl) return 1;

  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "X-API-Key: YOUR_TRACKSERVICEKEY");

  curl_easy_setopt(curl, CURLOPT_URL, "https://trackservice.trackroad.com/rest/credit");
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POST, 1L);

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);
  return (res == CURLE_OK) ? 0 : 1;
}

#import <Foundation/Foundation.h>

int main() {
  @autoreleasepool {
    NSURL *url = [NSURL URLWithString:@"https://trackservice.trackroad.com/rest/credit"];
    NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:url];
    [req setHTTPMethod:@"POST"];
    [req setValue:@"YOUR_TRACKSERVICEKEY" forHTTPHeaderField:@"X-API-Key"];

    NSURLSessionDataTask *task =
      [[NSURLSession sharedSession] dataTaskWithRequest:req
      completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        if (error) { NSLog(@"%@", error); return; }
        NSString *text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
        NSLog(@"%@", text);
      }];

    [task resume];
    [[NSRunLoop currentRunLoop] run];
  }
  return 0;
}

import Foundation

let url = URL(string: "https://trackservice.trackroad.com/rest/credit")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("YOUR_TRACKSERVICEKEY", forHTTPHeaderField: "X-API-Key")

let task = URLSession.shared.dataTask(with: req) { data, _, error in
  if let error = error { print(error); return }
  print(String(data: data ?? Data(), encoding: .utf8) ?? "")
}
task.resume()
RunLoop.main.run()

Keep API keys on the server side. Do not embed TrackServiceKey in browser JavaScript, mobile apps, or public client-side code.

SOAP authentication (SessionIDHeader)#

SOAP calls authenticate using SessionIDHeader. For TrackRoad SOAP services, send your TrackServiceKey as the SessionID value on every request.

Login and Logout may still appear in older SOAP documentation, but they are not required for modern integrations that already use TrackServiceKey.

<soap:Header>
  <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
    <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
  </SessionIDHeader>
</soap:Header>

Security best practices#

Protecting your API key is essential for reliable and secure production integrations.

Never expose API keys in front-end JavaScript.
Use secure server-to-server or backend integrations.
Store keys in environment variables, secret managers, or secured configuration stores.
Rotate the key immediately if you suspect compromise.
Never log or email API keys in plaintext.

Common errors (401/403)#

If authentication fails, verify the header name, key value, environment, and account status.

401 Unauthorized: missing or invalid key. For REST, check X-API-Key. For SOAP, check SessionIDHeader and SessionID.
403 Forbidden: the key may be valid, but access is blocked, expired, or limited by credit or permissions.

FAQ#

How do I authenticate TrackRoad REST API calls?

Send your TrackServiceKey in the X-API-Key header on every REST request.

How do I authenticate TrackRoad SOAP calls?

For SOAP, send your TrackServiceKey in SessionIDHeader as SessionID on each SOAP request.

Do I need Login/Logout?

No. Login and Logout endpoints are legacy. New integrations should use TrackServiceKey authentication.

Why do I get 401 Unauthorized?

Common causes include a missing X-API-Key header, an invalid key, extra whitespace, or using the wrong environment or host.

Next step: try an endpoint

Once you have your TrackServiceKey, start with Credit to validate authentication, then continue with Geocode, Route, Routes, or Dispatch.

Check Credit Go to Dispatch

Table of contents