Skip to content

API authentication

Enterprise feature

The REST API is available on Enterprise plans. Compare plans to find the right fit for your team.

Every request to the FSM Navigator™ API must include a valid API key. This guide covers how to create keys, assign scopes, restrict access by IP, and manage your keys over time.

API key format

API keys follow a predictable prefix pattern so you can identify them at a glance:

Environment Prefix Example
Production fsm_live_ fsm_live_a1b2c3d4e5f6...
Testing fsm_test_ fsm_test_x9y8z7w6v5u4...

Keys are long, randomly generated strings. Never share them in client-side code, public repositories, or unencrypted channels.

Create an API key

  1. Navigate to Settings → API Keys in your FSM Navigator dashboard.
  2. Click Create API Key.
  3. Enter a name for the key (e.g., "CRM Integration" or "Reporting Script").
  4. Select the scopes the key needs (see Available scopes below).
  5. Optionally add an IP whitelist to restrict where the key can be used.
  6. Click Generate.

Copy your key now

Your API key is displayed only once. Copy it to a secure location — such as a password manager or secrets vault — before closing the dialog. You cannot retrieve the key later.

Authenticate requests

Include your API key in the X-API-Key header on every request:

curl -X GET "https://fsmnavigator.com/api/v1/jobs" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

headers = {"X-API-Key": "YOUR_API_KEY"}
response = requests.get(
    "https://fsmnavigator.com/api/v1/jobs",
    headers=headers
)

const response = await fetch("https://fsmnavigator.com/api/v1/jobs", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
});

If the key is missing or invalid, the API returns 401 Unauthorized. See Error codes for details.

Available scopes

Scopes control which resources a key can access. Assign only the scopes your integration actually needs.

Jobs

Scope Grants access to
jobs:read List and retrieve jobs
jobs:write Create and update jobs

Customers

Scope Grants access to
customers:read List and retrieve customers and their locations
customers:write Create and update customers and their locations

Assets

Scope Grants access to
assets:read List and retrieve assets and service history
assets:write Create and update asset records
assets:transfer Transfer assets between locations
assets:meter Submit meter readings for assets
assets:service Create service and maintenance records for assets

Inventory

Scope Grants access to
inventory:read List and retrieve inventory items, stock levels, transactions, and locations
inventory:write Create and update inventory items and adjust stock
inventory:transfer Transfer stock between locations

Other

Scope Grants access to
technicians:read List and retrieve technicians and their availability
webhooks:manage Reserved for upcoming webhook subscription management

About the technicians scope

The technicians:read scope grants access to the technicians endpoint (GET /api/v1/technicians) for listing and retrieving technician records. Assigned-technician details also appear in job and asset responses when this scope is present.

Principle of least privilege

Create separate keys for different integrations and assign each key the minimum scopes it requires. This limits the blast radius if a key is compromised.

IP whitelist

You can restrict an API key so it only works from specific IP addresses or CIDR ranges.

  1. Open Settings → API Keys.
  2. Click the key name to edit it.
  3. Under IP Whitelist, add one or more IP addresses or CIDR ranges (e.g., 203.0.113.0/24).
  4. Click Save.

Requests from non-whitelisted IPs are rejected with 403 Forbidden.

No whitelist = all IPs allowed

If you leave the whitelist empty, the key accepts requests from any IP address.

Revoke a key

  1. Go to Settings → API Keys.
  2. Find the key you want to revoke.
  3. Click Revoke and confirm.

Revoked keys stop working immediately. Any integration using the key receives 401 Unauthorized from that point forward.

Best practices

  • Rotate keys regularly — create a new key, update your integration, then revoke the old key.
  • Use test keys during development — switch to a production (fsm_live_) key when you go live.
  • Store keys in environment variables — never hardcode keys in source code.
  • Monitor usage — check the API key dashboard to review request counts and last-used timestamps.

Frequently asked questions

Can I retrieve a key after creation?

No. API keys are displayed only once at creation. If you lose a key, revoke it and create a new one.

How many keys can I create?

There is no hard limit. Create as many keys as your integrations require.

Can I change a key's scopes after creation?

Yes. Open the key details in Settings → API Keys and update the assigned scopes.