Authentication

Every endpoint except the documentation itself requires a personal access token (PAT), sent as a bearer token:

Authorization: Bearer pat_XXXXXXXX_XXXXXXXXXXXX_XXXXXX

There is no OAuth flow, no API-key query parameter and no session cookie. A PAT is the only credential this API accepts.

Creating a token

Tokens are created in the Fieldnode web app under My Account → API tokens. They are not an administrator feature — any user can create one, and it carries that user's own permissions in their own organisation. A token can never do something its owner could not do in the UI.

The secret is shown once, at creation. It is not recoverable afterwards: the platform stores only a hash, so if you lose it, roll the token rather than trying to read it back.

When you create one you may set:

• An expiry. The window is stored as a duration, so rolling the token later re-applies the same window rather than extending it outward.
• An IP allow-list, as one or more CIDR ranges. See below.

What is checked on every request

A token has to clear all of the following:

1. The token row exists.
2. Its secret matches.
3. It has not been revoked.
4. It has not expired.
5. Its owning user is still active.
6. Its owning organisation is still active.
7. The client IP is admitted by the token's IP allow-list, when it has one.

Any failure returns 401 with the same message — invalid token — regardless of which check stopped it. Which control refused an unauthenticated caller is not information that caller is entitled to.

IP restrictions

A token may be pinned to one or more CIDR ranges, and the check fails closed: if the client IP cannot be determined, a restricted token is refused. This matters behind a proxy — if X-Forwarded-For is stripped somewhere in front of the API, a restricted token stops working rather than silently losing its restriction.

An unrestricted token is unaffected.

Rolling and revoking

Rolling mints a new secret for the same token, keeping its name, expiry window and IP restrictions. The old secret stops working immediately. This is the right response to a leak, and the right habit on a schedule.

Revoking disables the token permanently. It cannot be un-revoked; create a new one instead.

Editing a token's name or IP allow-list leaves the secret working. Expiry is deliberately not editable — extending the life of a secret that may already have leaked is exactly the thing worth preventing, so a longer window means a new secret.

Handling tokens well

• Keep tokens in a secret store or environment variable. Never commit one, and never put one in a URL — query strings end up in logs, proxies and browser history.
• Give each integration its own token, so one can be rolled without disturbing the others.
• Set an IP allow-list whenever the caller has a stable egress address.
• Treat a 401 as terminal rather than retrying: the token is wrong, and retrying will not fix it.