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

Other

Scope Grants access to
technicians:read View technician data embedded in job and asset responses
webhooks:manage Create and manage webhook subscriptions

About the technicians scope

The technicians:read scope does not have a dedicated endpoint. Instead, technician details (name, ID) appear automatically in job and asset responses when a technician is assigned. Include this scope if your integration needs to read assigned technician information.

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.