Create, scope, rotate, and revoke FieldCamp API keys with /api/v1/api-keys to give every integration its own credentials.

FieldCamp API keys are the credentials your integrations, scripts, and partner apps use to call the platform on your behalf. The /api/v1/api-keys endpoints let you list, create, retrieve, update, and delete personal-access-style keys — each with its own scopes, expiry, and rate-limit overrides — so every integration gets a credential matched to exactly what it needs to do.

This guide walks dispatchers, owners, and developers through the day-to-day operations of API key management: minting a new key for a new integration, narrowing its scopes, setting expiry dates, rotating compromised keys, and revoking access cleanly when a vendor or team member moves on. If you are still issuing a single shared key, this is the workflow that gets you to a safer per-integration setup. For a broader tour of every endpoint and resource, start with the API reference overview.

What API keys are for

API keys identify the calling app and authorize the actions it can take. They sit alongside the JWT described in Authentication and inherit your tenant's rate limits by default. Each key is owned by your company and can be assigned to a specific integration — a website booking widget, a QuickBooks sync, a custom dashboard, or an internal automation built with the workflow automation engine.

Per-key scoping means a read-only reporting tool never needs the same powers as a job-creation worker. Smaller blast radius if a key leaks.

Plan your keys before you create them

A few minutes of planning saves cleanup later. For every integration, decide:

Owner — who in your team is responsible if it breaks
Scopes — the minimum set of resources it must read or write
Expiry — a hard end date for short-lived projects, or a rotation cadence (90 days is a common default) for long-lived ones
Rate-limit override — only if the integration genuinely needs more throughput than the default tenant limit

Name keys after the integration, not the person — booking-widget-prod, quickbooks-sync, bi-dashboard-read. When someone leaves the company, you do not have to rename anything.

Create an API key

POST to /api/v1/api-keys

Send a POST request with a friendly name, the scopes array, and optional expiresAt and rateLimit fields. The response contains the full key string once — store it immediately in your secrets manager.

Save the secret

The plaintext key is only returned on creation. After that you only ever see the key's metadata (name, scopes, expiry, last used). If you lose it, rotate and re-issue.

Test with a low-risk call

Verify the key against GET /api/company-info or another read endpoint before wiring it into production. See the Company Info resource for the response shape. If you get a 401, double-check the headers per Authentication.

Deploy and monitor

Add the key to your integration's environment variables and ship. Watch the first few hours of requests for 429s — if you see them, revisit your rate-limit override or back-off logic.

Scope keys to the minimum needed

Scopes let you grant only the resources an integration really uses. A reporting tool that reads jobs and visits does not need write access to clients or items. Common scope patterns:

Read-only analytics — jobs:read, visits:read, clients:read
Booking-widget intake — clients:write, jobs:write (no delete)
Accounting sync — invoices:read, clients:read, plus webhook delivery
Full admin automation — everything, but only for trusted internal tools

If you are not sure which scopes a key needs, start narrow and widen based on the 403s you see. The error responses from FieldCamp explicitly tell you which scope was missing — see Errors for the response shape.

Set expiry and rotate keys regularly

Long-lived secrets are the riskiest secrets. Use the expiresAt field to put a hard ceiling on every key, then rotate before it expires.

Mint a new key alongside the old one

Create the replacement with the same scopes and a fresh expiry. Both keys are valid at this point.

Deploy the new key

Update the integration's environment, redeploy, and verify it is calling FieldCamp successfully. Use the idempotency patterns so re-running a deploy does not duplicate records.

Watch the old key go idle

Check lastUsedAt on the old key. Once it has not been used for a full day, you know nothing is still depending on it.

Delete the old key

DELETE /api/v1/api-keys/{id} revokes it permanently. Any request carrying the old key now returns 401.

Never delete a key without confirming via lastUsedAt that nothing is still using it. Surprise revocations break production integrations and trigger angry calls from your dispatch team.

Override the default rate limit

The default tenant rate limit is shared across all keys. If one integration legitimately needs more headroom — say, a nightly batch import — give just that key a higher per-key limit instead of raising the whole tenant ceiling. This protects your interactive flows (command centre, universal search, calendar) from being starved by a runaway script.

See Rate limits for the headers FieldCamp returns and a sample back-off strategy.

Rotate immediately if a key leaks

A leaked key is a live credential. If a developer pastes one in a public repo, a screenshot ends up in a support ticket, or a laptop is lost, treat it as compromised and rotate now.

Delete the leaked key

Hit DELETE /api/v1/api-keys/{id} first to stop the bleeding. The leaked credential is now dead.

Audit recent activity

Pull the last 24-48 hours of activity for that key. Look for unusual job creation, unexpected client updates, or any change you did not authorize — you can cross-reference with job logs and any webhook events that fired.

Issue a replacement

Create a new key with the same scopes (or narrower, if the leak proved scopes were too wide) and deploy it.

Update the secret store

Rotate the value in every place it was stored — secrets manager, CI variables, local .env files, deployment platform. Then invalidate any cached copies.

Audit and clean up keys quarterly

Run through your key list at least every quarter. GET /api/v1/api-keys returns every active key with its scopes, expiry, and last-used timestamp. For each key, ask:

Is the owning integration still running?
Are the scopes still the minimum it needs?
When was it last used? Anything dormant for 60+ days is a candidate for deletion.
Has it been rotated this calendar quarter?

Authentication overview

How keys travel in the request headers and how FieldCamp validates them.

Errors reference

The error shapes you will see when a scope is missing or a key is revoked.

Common pitfalls

Sharing one key across every integration. A leak takes everything down at once. Issue one per integration.
Embedding keys in client-side code. Browsers and mobile apps are public surfaces. Always proxy through your own backend.
Forgetting expiresAt. Keys without expiry quietly become forever-keys. Always set one.
Granting * scope by default. Reach for the broadest scope only when you have confirmed a narrower set will not work.
Not testing after rotation. Always hit a real endpoint with the new key before flipping production traffic.

If your team is new to working with the FieldCamp API, walk through the quickstart first, then come back to set up per-integration keys once you have one integration working end to end. You can also follow the API changelog so you know when new scopes or endpoints land.

Managing FieldCamp API keys: create, scope, and rotate