API scopes¶

Scopes are permissions that control what an API key can do. Think of them like a keycard — each scope unlocks access to a specific part of the API while keeping everything else locked.

How scopes work¶

When you create an API key, you select exactly which scopes it should have. Then, every time you make an API request:

1. FSM Navigator checks the scopes assigned to your key.
2. If the key has the required scope, the request is processed.
3. If the key is missing the required scope, you receive a 403 Forbidden error.

Scopes follow a resource:action format. For example:

• jobs:read — permission to read job data
• jobs:write — permission to create and update jobs
• customers:read — permission to read customer data

You can update a key's scopes at any time from Settings → Company Settings → API Keys without regenerating the key itself.

Available scopes¶

FSM Navigator offers fourteen scopes across six resource types:

Write-implies-read behavior¶

Any scope that grants write, transfer, meter, or service access automatically includes the corresponding read access for the same resource. This is enforced server-side — you do not need to request both scopes.

Scope-to-endpoint mapping¶

Each API endpoint requires a specific scope. Use this table to determine which scopes your integration needs.

Jobs¶

Customers¶

Assets¶

Inventory¶

Technicians¶

Choosing the right scopes¶

Follow the principle of least privilege: only grant a key the scopes it actually needs. If your integration only reads data, don't add write scopes.

Common integration scenarios¶

Error responses¶

If you make a request that requires a scope your key doesn't have, the API returns a 403 Forbidden response:

{
  "success": false,
  "error": "insufficient_scope",
  "message": "Required scope: assets:write",
  "required_scope": "assets:write"
}

Quick example¶

A key with only jobs:read can list jobs but cannot create them:

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

{
  "success": true,
  "data": [
    {
      "job_id": 42,
      "job_title": "AC Repair",
      "job_status": "Pending"
    }
  ]
}

curl -X POST "https://fsmnavigator.com/api/v1/jobs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title": "AC Repair", "job_priority": "High"}'

{
  "success": false,
  "error": "insufficient_scope",
  "message": "Required scope: jobs:write",
  "required_scope": "jobs:write"
}

Important notes¶

Next steps¶

• Authentication — learn how to create and manage API keys
• Endpoints overview — full list of available endpoints
• Error codes — complete error reference
• Best practices — tips for building reliable integrations