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/Logout endpoints are legacy. New integrations should use TrackServiceKey authentication.

Why do I get 401 Unauthorized?

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

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.

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/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

How authentication works#

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

Recommended: use REST for new integrations. Use SOAP only for legacy systems.

Generate your TrackServiceKey#

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

If you cannot find TrackServiceKey, contact TrackRoad Support for API access.

REST authentication (X-API-Key)#

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

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 server-side. Do not embed keys in browser or mobile client code.

SOAP authentication (SessionIDHeader)#

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

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

Security best practices

Never expose API keys in front-end JavaScript
Use server-to-server calls (backend integrations)
Store keys in environment variables / secret managers
Rotate the key if compromised
Never log API keys

Common errors (401/403)#

401 Unauthorized: missing/invalid key (REST: missing X-API-Key; SOAP: missing/invalid SessionIDHeader).
403 Forbidden: key is valid but blocked/expired or account lacks credit/permissions.

Next step: try an endpoint

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

Check Credit Go to Dispatch

Table of Contents