Authentication

FieldTask has three kinds of connection. Each belongs to one organization and has its own permissions.

Connection	Use it for	Credential
API token	Your own scripts, servers and integration tools	A token you send as a bearer token
OAuth client	Integrations that already use OAuth client credentials	A client ID and secret, exchanged for short-lived access tokens
AI assistant (MCP)	AI clients such as Claude or ChatGPT	A sign-in by an owner or admin; there's no key to copy

All three are managed by organization owners and admins in Settings → API connections. Before anyone can create a connection, FieldTask must enable API access for the organization; an owner or admin requests it with Request API access.

API tokens

API tokens are the simplest way to call the REST API. There's no token exchange: send the token in every request.

curl "$FIELDTASK_API_ORIGIN/public/v1/jobs" \
  --header "Authorization: Bearer $FIELDTASK_API_TOKEN"

Create a token

1. Open Settings → API connections and choose Create API token.
2. Enter a name you'll recognize later.
3. Choose a permission preset (Read only, Read + create or Custom). See Permissions.
4. Choose when it expires: Never, 30 days, 90 days or 1 year.
5. Copy the token. It's shown only once, and the dialog stays open until you choose I've saved it. Afterwards, FieldTask shows only its last four characters, its expiry and when it was last used.

API tokens start with ft_. Keep them on your server or in a secret store, never in browser or mobile app code.

Change permissions

Choose Manage on the token's connection to add or remove permissions. The token string stays the same, and changes apply from the next request.

Rotate a token

Choose Rotate token, pick the new token's expiry, then either:

• Rotate now: the old token stops working immediately. Use this if the token may have leaked.
• Rotate with 7-day overlap: the old token keeps working for 7 more days while you update your integration. If the old token would have expired sooner, it still expires then. During the overlap, the connection list shows the new token.

Copy the new token; it's shown only once.

Rotating keeps the same connection, so idempotency keys you already used stay valid for retries.

OAuth client credentials

Use an OAuth client if your integration already follows the OAuth 2.0 client-credentials flow. Create one under For developers with Register OAuth client, and save the client ID and secret; the secret is shown only once.

Request an access token from the token endpoint. Send the client credentials with HTTP Basic authentication, and set resource to the REST resource shown with your connection:

curl --request POST "$FIELDTASK_API_ORIGIN/o/token/" \
  --user "$FIELDTASK_CLIENT_ID:$FIELDTASK_CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "resource=$FIELDTASK_REST_RESOURCE" \
  --data-urlencode "scope=jobs:read customers:read"

The response contains access_token, token_type and expires_in. Use the access token as a bearer token until it expires, then request a new one with the same request.

• resource must be sent exactly once and must match the REST resource; otherwise the response is invalid_target.
• scope lists the permissions you want, separated by spaces. A token can't have more permissions than its connection.
• The token endpoint returns standard OAuth error responses, not the API's problem format.

Rotate a client secret

Choose Rotate secret on the connection, save the new secret, then activate it. When you activate, choose whether the previous secret stops working immediately or keeps working for 7 days.

AI assistants (MCP)

AI clients connect through MCP with an OAuth sign-in. An organization owner or admin signs in to FieldTask from the client, chooses the organization and permissions, and approves. The client then acts on that person's behalf, within the approved permissions.

See Connect an AI client for the steps.

• Only owners and admins can approve an MCP connection.
• Added permissions need approval. When an admin adds a permission to an assistant's connection in Settings → API connections, it waits for approval. The person who connected the assistant must reconnect it and approve the new access; then refresh the client's tools.
• Removed permissions apply immediately, and approving again can't restore a permission an admin removed. An admin must add it back.
• Reconnect in Manage signs the assistant out so it can connect again.
• Each person can also review and disconnect their own assistant connections from the sign-in pages.

MCP sign-ins only work with the MCP server. They can't call the REST API, and REST tokens can't be used with MCP.

Limits and revocation

• An organization can have up to 100 active connections.
• Revoke a connection in Settings → API connections to stop it immediately. Records it already created stay in FieldTask. Revoking can't be undone; create a new connection instead.
• FieldTask can also turn off API access for a whole organization. Existing tokens then fail with api_access_not_enabled.
• Every request is checked against the connection's current permissions and the organization's current access, not only when the token was issued.

Keep credentials safe

• Store tokens and secrets in a secret manager or environment variables, never in source control.
• Use a separate connection for each integration, so you can revoke one without affecting others.
• Give each connection only the permissions it needs.
• Never include tokens, secrets or invitation links in support requests.