FieldCamp API Authentication and Scopes

Authenticate FieldCamp API requests with fc_live API keys, choose the required resource scopes, and troubleshoot 401, 403, and 429 responses.

FieldCamp public API routes use API keys that begin with fc_live_. Each key belongs to one FieldCamp account, has its own scopes and rate limit, and can have an expiry date.

This guide assumes that FieldCamp has already issued a valid key for your integration. API-key provisioning is outside the public authentication flow described here.

An API key is a credential. Keep it on a trusted server, never put it in browser code, and never commit it to source control.

Send an authenticated request

Send the key in one of these headers:

X-Api-Key: fc_live_...
Authorization: Bearer fc_live_...

Use one authentication header per request. When X-Api-Key is present, FieldCamp evaluates that value first.

curl https://api.fieldcamp.ai/api/v1/jobs \
  -H "X-Api-Key: $FIELDCAMP_API_KEY"

const response = await fetch('https://api.fieldcamp.ai/api/v1/jobs', {
  headers: {
    Authorization: `Bearer ${process.env.FIELDCAMP_API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`FieldCamp API returned ${response.status}`);
}

const body = await response.json();

The key must be active, unexpired, and associated with the FieldCamp account that owns the requested data. See the Jobs API reference for request and response details used in this example.

Choose the required scopes

FieldCamp checks the scopes required by each route. Read and write permissions are separate for core resources.

Scope	Required for
`clients:read`	List or retrieve clients.
`clients:write`	Create, update, or delete clients.
`jobs:read`	List or retrieve jobs.
`jobs:write`	Create, update, or delete jobs.
`visits:read`	List or retrieve visits.
`visits:write`	Update visits.
`invoices:read`	List or retrieve invoices and supported payment links.
`invoices:write`	Create, update, or delete invoices.
`integrations:write`	Run the supported Google Calendar and QuickBooks integration routes.
`webhooks:manage`	Create, list, update, delete, and inspect webhook endpoints and deliveries.

Webhook management requires webhooks:manage. The integrations:write scope does not authorize /api/v1/webhooks.

When an integration needs several route families, include every required scope on its key. Start with the smallest set that supports the intended workflow.

Use the webhook management scope

Every route in the webhooks API requires webhooks:manage, including:

GET and POST /api/v1/webhooks
GET, PUT, and DELETE /api/v1/webhooks/{id}
GET /api/v1/webhooks/{id}/deliveries

If webhook creation returns 403, create or update the key with webhooks:manage and try again. Do not substitute integrations:write; that scope belongs to integration sync routes.

Understand authentication failures

401 Unauthorized

FieldCamp returns 401 when no API key is present or when the key is invalid, inactive, or expired.

Check that:

the value includes the fc_live_ prefix;
the header contains the complete key;
the key has not been revoked;
its expiry date has not passed; and
the integration is using the newly issued value after a rotation.

403 Forbidden

The key is valid, but it does not include every scope required by the route. Compare the request method and route with the scope table, then issue a key with the missing scope.

429 Too Many Requests

The key exceeded its configured rate limit. A rate-limited response includes:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Wait until the reset time and retry with backoff. Do not immediately repeat the same request in a tight loop.

Handle standard API errors explicitly in your integration instead of retrying every response.

FieldCamp API Authentication and Scopes

On this page