How to authenticate with the FileMaker Data API

You want to pull orders from FileMaker into your webshop, or push customer records into FileMaker from a signup form — but the moment you start reading the FileMaker Data API documentation, you hit a wall of terms: bearer tokens, session tokens, Basic Auth, OAuth providers, X-FM-Data-Access-Token. Nothing seems to just "work" the way a typical REST API key does, and the first integration attempt often fails with a cryptic 401 or 952 error before a single record is ever exchanged.

This article walks through exactly how authentication works in the FileMaker Data API, why it's built the way it is, and how to set it up correctly the first time — so your integration doesn't break in three months when a token silently expires.

Why doesn't the FileMaker Data API just use a simple API key?

Most modern SaaS APIs (Stripe, Mailchimp, Shopify) hand you one static API key and you're done. The FileMaker Data API deliberately does not work that way, because it isn't a public API for a single hosted service — it's a gateway into a live, hosted FileMaker database that may contain sensitive customer, financial, or HR data, sitting on your own server (or Claris Cloud/FileMaker Server).

Instead, FileMaker uses a session-based token model: you authenticate once with real credentials, FileMaker Server hands you back a temporary session token, and every subsequent request uses that token instead of your username and password. This is closer to how a web app manages login sessions than how a typical API vendor issues keys — and it exists specifically so that raw credentials aren't passed around on every single call.

What are the actual authentication methods available?

There are three practical ways to authenticate against the FileMaker Data API:

1. Basic Authentication with a FileMaker account — you send a base64-encoded username/password in the request header to the /sessions endpoint. This is the most common method for server-to-server integrations (e.g. an ERP nightly sync job).
2. Claris ID / external identity provider (OAuth) — if your FileMaker file is configured with an external OAuth provider (Google, Microsoft Azure AD, Amazon), users authenticate through that provider and FileMaker exchanges the OAuth token for a session token. This is typically used when end-users (not scripts) are logging in through a custom web or mobile front end.
3. API keys via FileMaker Server 2023+ / Claris Cloud for certain managed integrations — a lighter-weight option in newer versions, but still ultimately issuing a session token behind the scenes.

For most B2B integrations we build at Loggix — connecting FileMaker to an accounting package, a webshop, or an internal API layer — Basic Auth against a dedicated FileMaker account is the practical default, because it's scriptable, doesn't require a live user, and works identically on-premise and in the cloud.

How do you get your first session token, step by step?

Here's the actual flow, using a concrete example: a nightly job that syncs new orders from FileMaker into an external accounting system.

1. Create a dedicated FileMaker account for the integration — never reuse a human user's login. Give this account a Privilege Set scoped only to the layouts and scripts the integration actually needs (e.g. Orders_API layout, read/write on Orders table only).
2. Send a POST request to: https://yourserver.com/fmi/data/vLatest/databases/YourDatabase/sessions with an Authorization: Basic <base64(username:password)> header and an empty JSON body (or a fmDataSource array if you need external data sources authenticated too).
3. Receive the response — a JSON payload containing response.token, a session token string.
4. Use that token on every following request as: Authorization: Bearer <token>
5. Reuse the token for all calls within the session — do not request a new token per record. One token, many requests.
6. Close the session explicitly with a DELETE request to the same /sessions/<token> endpoint when the job finishes, to free up the license seat and avoid orphaned sessions piling up on the server.

[[IMAGE:left|client sending credentials, server returning a token, then repeated API calls]]

How long does a session token actually last?

By default, a FileMaker Data API session token expires after 15 minutes of inactivity — not 15 minutes total. Every request you make resets that 15-minute clock. This is a detail that trips up a lot of first-time integrations: a batch job that pauses for 20 minutes between record 500 and 501 (e.g. waiting on a slow external API rate limit) will suddenly get a 401 and assume the whole integration is broken, when really the token simply went idle too long.

The practical fix: build token-expiry handling into your integration logic from day one — catch the 401, request a fresh session, and retry the failed call — rather than treating expiry as an edge case you'll deal with later.

What are the most common authentication mistakes teams make?

• Hardcoding a token instead of a login flow. Tokens are session-scoped and short-lived; a token copied into a config file will die within 15 minutes. Always automate the login step.
• Requesting a new token for every single record. This is slow, wastes license seats, and can hit FileMaker Server's concurrent session limits on busy systems.
• Never closing sessions. Each open session consumes a client connection slot on FileMaker Server. Integrations that never call the DELETE /sessions endpoint can quietly exhaust the server's connection limit, causing unrelated users to get locked out.
• Using a full-access admin account for the integration. If that account (or its credentials, stored in a script or middleware config) is ever exposed, the integration has full access to every table and script in the file — not just Orders.
• Storing credentials or tokens in plain text inside a middleware tool, Zapier scenario, or custom script without any secrets management. Treat FileMaker integration credentials with the same care as a database admin password, because functionally that's what they are.
• Assuming HTTPS is optional on internal networks. FileMaker Server requires SSL for Data API calls by default, and for good reason — Basic Auth sends encoded, not encrypted, credentials, so this only stays safe over TLS.

How does this fit into a bigger connectivity strategy?

Authentication is only the entry point — the real value shows up once you decide what the FileMaker Data API should connect to and how those connections should be maintained over time. If you're mapping out a broader plan for linking FileMaker to accounting software, webshops, or internal APIs, our guide on how to connect FileMaker to modern applications and services covers the wider architecture decisions — middleware vs. direct calls, sync frequency, and error handling — that sit around this authentication layer.

Quick checklist before you go live

• Dedicated FileMaker account created, with a minimal, purpose-built Privilege Set
• Login flow automated (not a hardcoded token)
• Token reused across the full session, not re-requested per record
• 401 handling built in to silently refresh an expired token and retry
• Sessions explicitly closed (DELETE) when a job finishes
• SSL/HTTPS enforced on the FileMaker Server
• Credentials stored in a secrets manager or encrypted config, not plain text
• Session/connection limits on FileMaker Server checked against expected integration load

FAQ: FileMaker Data API authentication

Can I use the same account for multiple integrations? Technically yes, but it's not recommended. Separate accounts per integration make it far easier to audit, throttle, or revoke access to one connection without breaking the others.

Does the Data API support two-factor authentication? Not directly for Basic Auth service accounts — 2FA applies to human logins via Claris ID/OAuth providers. Service-to-service integrations rely on account-level access control and network security (IP restrictions, VPN, firewall rules) instead.

What's the difference between the Data API and OData in FileMaker? Both can authenticate similarly (Basic Auth, OAuth), but OData is aimed at read-heavy reporting/BI tool connections, while the Data API is built for full read/write application integrations. If your use case is a live sync (not just reporting), the Data API is almost always the right layer.

What happens to open sessions if FileMaker Server restarts? All active session tokens are invalidated immediately. Any integration should be built to detect this (a 401 response) and simply log in again — it's a normal event, not a failure state.

Getting authentication right is a small technical detail with a large downstream impact: it determines how secure, stable, and maintainable every future integration built on top of it will be. If you're planning to connect FileMaker to an ERP, webshop, or external API and want the authentication layer — and everything built on it — designed properly from the start, Loggix can help map out the right architecture, build the custom FileMaker solution or API connector itself, and make sure the integration keeps running reliably long after go-live.