Authentication

Every request to the public API carries the key in the X-API-Key header:

X-API-Key: 8f14e45fceea167a5a36dedd4bea2543a1b0c9f2e4d7b8a6c3e5f9d2a4b6c8e0

Authorization: Bearer doesn't work

Authorization: Bearer <key> is reserved for the app’s session tokens: an API key passed there is rejected with 403. Always use the dedicated X-API-Key header.

Creating a key

Create a key from Settings → API Keys → New key; it is shown in clear text only once, at creation time. We only keep its SHA-256 fingerprint and the first six characters (to recognize it in the list) — nobody can read it back, not us, not an administrator, not someone who stole a copy of the database. If you lose it, revoke it and create another.

A key acts on your account from the outside, without a user session: treat it like a password.

Permissions (scopes)

A key can’t do anything it doesn’t have permission for: permissions are granted one by one, at creation or when editing.

Permission	Unlocks
read_devices	Device list and details
read_locations	Latest known position
read_history	Position history
read_history_summary	Aggregated position history
read_events	Fleet events
send_commands	Command queue — read-only in API v2

Without the permission, the response is 403:

{ "error": "API key senza permesso: read_devices" }

Note

Sending commands is not exposed in v2: a key can read the queue, not move a vehicle. This is a security choice (remote engine cut is a sensitive capability), not an oversight.

IP restriction (optional)

You can attach an allowlist of up to 50 entries to a key: single IPv4 addresses or CIDR notation (10.0.0.0/24), IPv6 only as an exact address. A call from an IP outside the list is rejected with 403 and code API_KEY_IP_BLOCKED, even with a valid key. An empty or absent allowlist means no IP restriction.

Rate limits

Limit	Value
Per key, per minute	120
Per key, per hour	1000
Per IP address, per minute	120

Over the limit, the response is 429. Responses do not carry X-RateLimit-* or Retry-After headers: size your client around the numbers above.

Example: first authenticated call

cURL

curl https://api.aitrack.it/api/v2/devices?limit=10 \
  -H "X-API-Key: $AITRACK_API_KEY"

Node.js

const response = await fetch('https://api.aitrack.it/api/v2/devices?limit=10', {
  headers: { 'X-API-Key': process.env.AITRACK_API_KEY },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Aitrack API error: ${JSON.stringify(error)}`);
}

const { data, meta } = await response.json();
console.log(data, meta);

Python

import os
import requests

response = requests.get(
    "https://api.aitrack.it/api/v2/devices",
    headers={"X-API-Key": os.environ["AITRACK_API_KEY"]},
    params={"limit": 10},
    timeout=10,
)
response.raise_for_status()
body = response.json()
print(body["data"], body["meta"])

Revocation

If you suspect a key has leaked, revoke it immediately from API Keys: it stops working on the very next call. Revoked keys never become active again.

Keeping a key safe

• Put it in an environment variable. Never in your site’s code, never in a repository: a key in a public repo is an open door to your fleet.
• One key per integration, so revoking one doesn’t break the others.
• Restrict by IP when you can: a stolen key from a disallowed address is useless.