Introduction

This tutorial is your comprehensive, practical guide to OData in FileMaker Server 21.1.x and beyond, designed for engineers who want to understand, implement, and troubleshoot real-world OData integrations with FileMaker.

Why OData Matters

OData (Open Data Protocol) is now a first-class feature of FileMaker Server, enabling standard, RESTful access to your data for reporting, integration, automation, and analytics—using tools like Excel, Power BI, Tableau, Postman, and any custom app or AI agent that speaks OData. But while OData brings unprecedented openness and power, it also introduces new security and architecture considerations for the FileMaker community.

About This Tutorial

This guide is rooted in real-world scenarios, common errors, and proven solutions, not just theoretical best practices. It is structured around step-by-step instructions, annotated troubleshooting tables, and detailed privilege/account setup examples, all validated against FileMaker Server 21.1.5 as of June 2025.

Community Credits

Special credit and thanks go to two leading figures whose work has laid the foundation for the entire FileMaker OData learning community:

• John Renfrew
  John’s tireless advocacy, training, and deep dives—most notably his legendary “5-day OData Bootcamp” (FMTraining.tv)—have been essential for raising awareness, demystifying OData, and equipping FileMaker developers worldwide with practical OData skills. Since 2019, John has been “preaching OData” at DevCons, online sessions, and forums, patiently answering questions and sharing updated examples with every new FileMaker release.
• Steve Senft-Herrera (Beezwax)
  Steve’s OData for FileMaker – Examples, Tips and Nuances (Beezwax blog, 2021) set the community benchmark for OData demo files and code samples. His public example files, extensive cURL scripts, and early documentation remain the go-to resource for anyone learning to test, script, or troubleshoot FileMaker OData access.

Without the ongoing work of John Renfrew and Steve Senft-Herrera, there would be no standard reference for OData in the FileMaker world. This tutorial stands on their shoulders and is designed to extend their work with validated, version-specific, and future-proofed practices.

Let’s get started with OData for FileMaker—from first connection, to error handling, to secure, production-ready integration.

Note to the Reader:
This guide does not waste your time with comparisons to legacy database technologies, driver installation headaches, or ODBC/JDBC/DSN war stories.

If you’re here, you want to implement and secure OData in FileMaker Server—full stop.

OData is the standard way to expose your FileMaker data to the world. You don’t need to know or care about what came before.

We focus only on what you must know to get OData working, secured, and production-ready—no distractions.

Step 1.0: Enabling OData in FileMaker Server 21.1.x

Before any OData API integration, you must explicitly enable OData in the FileMaker Server Admin Console or via CLI.

OData is disabled by default for security.

If the service is not running, all OData endpoints will return HTTP 502.x – Bad Gateway (IIS/Nginx).

A. Enabling OData – Admin Console (All Platforms)

1. Login to the FileMaker Server Admin Console in your browser.
2. Go to Connectors.
3. Select the OData tab on the left.
4. Set OData toggle to Enabled.
5. Wait for confirmation.

http(s)://<yourServer>:16001/admin-console/app/connectors/fmodata

Dimitris Asks:
“What happens if I forget to enable OData?”
You will receive 502.x errors or equivalent. No endpoint will respond until the listener is enabled and running.

B. Enabling/Controlling OData – CLI (Command Line)

Windows

• Open PowerShell as Administrator.
• Run: fmsadmin start odata
  • No credentials are required (major security gotcha: see below).
• To stop: fmsadmin stop odata
  • Prompts for Y/N, no password.

PS C:\Users\user> fmsadmin start odata
PS C:\Users\user>

PS C:\Users\user> fmsadmin stop odata
C:\Program Files\FileMaker\FileMaker Server\Database Server\fmsadmin.exe: really stop odata? (y, n) y
PS C:\Users\user>

Linux

• Open a root shell (or use sudo).
• Run: fmsadmin start odata
  • BUT: Sometimes, if OData was stopped via the CLI, you cannot re-enable via CLI (Error 10017: “Requested object is disabled”).
    Only Admin Console (browser) can re-enable OData.

user@vm:~$ fmsadmin start odata
user@vm:~$

user@vm:~$ fmsadmin stop odata
fmsadmin: really stop odata? (y, n) y
user@vm:~$

Security & Operational Gotchas

• Security Bug:
  On both Windows and Linux, fmsadmin start odata and fmsadmin stop odata do NOT require credentials if run locally.
  All other admin commands do require authentication.
  • Risk: Any local admin (or root) can disrupt OData APIs without trace or challenge.
  • Mitigation:
    • Lock down server OS access.
    • Monitor and audit admin access.
    • Reported as bug to Claris (as of June 2025).
• CLI/UI Parity Bug (Linux):
  • If OData is disabled in Admin Console, CLI cannot re-enable.
  • Symptom:
    • CLI: Error 10017 “Requested object is disabled.”
    • Only the Admin Console UI can fully re-enable OData after disable.
  • Impact:
    • Automated recovery scripts on headless/remote servers will fail to recover OData after an admin disables it via UI.
• Version Specific:
  • Behavior confirmed for FileMaker Server 21.1.5 (current as of June 2025).
  • Always verify on your specific version.

RTFM / References

• Claris FileMaker 21.1.5 OData API Guide (2024)
• Monitor OData access
• Starting or stopping FileMaker Server components
• CLI Reference – fmsadmin

OData Endpoint Troubleshooting Table

Special Case: All Tables Hidden

• If all tables/TOs have “no access” (custom record privileges set to none) for the active privilege set:
  • The file will appear in the OData database list.
  • No entity sets/tables will be visible under that file in OData.
  • This is not an error—it’s the correct “least privilege” behavior.

Step 2.0: Authentication Behavior When Accessing OData Endpoint in Browser

When you visit the OData root endpoint in a browser:


https://<yourserver>/fmi/odata/v4/

the following authentication scenarios occur:

a) User Cancels the Login Dialog

Behavior:
The browser immediately returns:

Error Code: 18
Error Message: (18): Login required

Explanation:
No credentials were provided. The OData listener requires HTTP Basic authentication for all requests.

b) User Enters Incorrect Credentials

Behavior:
The browser displays:

Error Code: 9
Error Message: (9): Access denied

Explanation:
The username/password was not valid for any account with the [fmodata] extended privilege in any hosted file. The OData listener rejects the request.

c) User tries access a file that is not Open or does not exist

Behavior:
The browser displays:

Error Code: 802
Error Message: (802): Unable to open file

Explanation:
This is a “core” FileMaker error—802: Unable to open file—that OData passes back unaltered if the endpoint is valid but the file isn’t open/hosted.

It’s distinct from authentication/privilege errors: the file simply isn’t accessible at all, regardless of credentials.

d) User Enters Correct Credentials

• Behavior:
  If authentication succeeds, you see a list of all databases accessible to that account (i.e., files open on the server with [fmodata] enabled and proper privilege set).
• Explanation:
  Authentication succeeded. The OData endpoint now displays the available databases, and navigation can proceed to table/entity listing.

e) Force Login as a Different User (Bypass Cached Credentials)

Method:
Use the URL format:

 https://userName:passWord@<yourserver>/fmi/odata/v4/ 

Behavior:
The browser automatically submits the provided credentials for HTTP Basic authentication, bypassing any cached or previously entered credentials.

Note:
Most modern browsers may still cache credentials for the session or domain.

Use Incognito/Private mode, if login issues persist.

Authentication “Gotchas” for Browser Access

• Forcing re-authentication with another user:
  • Use: https://username:password@yourserver/fmi/odata/v4/
  • This always works (it overrides cached credentials in Chrome and other browsers).
• To use a different user without browser restart:
  • Use Incognito/Private Browsing Mode (Ctrl+Shift+N).
  • Each Incognito session prompts for credentials, with no cache, after you close any previous Incognito window.
• Site Data/Cookie clearing:
  • Deleting cookies or site data in Chrome does not clear HTTP Basic Auth credentials cache.
  • Incognito Mode is the only guaranteed user-friendly option.

Practical Gotchas:

• OData authentication is always per HTTP request (stateless, Basic Auth), unlike WebDirect or Data API tokens.
• If a user does not have the [fmodata] privilege in any open file, they will see Error 9 (“Access denied”) even if the account exists.
• Always test access with real OData users, not Full Access or “admin” accounts unless intentionally exposing all tables.

OData/REST: The FileMaker Reality (No Layouts, No UI!)

Key Principle:

OData exposes your raw data—every Table Occurrence (TO) you allow, every field you don’t explicitly lock down.

There is no context, no layouts, no UI, no hidden magic.

What you see in your Relationship Graph and Privilege Sets is exactly what OData exposes.

If you want to hide it, restrict the Privilege Set or remove it from the graph.

⚠️ WARNING: OData ignores all FileMaker layouts, interface security, script triggers, and UI-based field hiding. Security is enforced only at the table/TO and field privilege level.

Step 3.0: Preparing the Demo File for OData Security/Privilege Testing

Reference Demo File:
This tutorial uses the sample file from the highly recommended Beezwax blog post:
“OData for FileMaker – Examples, Tips and Nuances” by Steve Senft-Herrera (Beezwax).
This is also the file recommended by John Renfrew for OData learning and security demonstration.

Download the Sample File:

• Beezwax_OData_Examples_20210303_2037.zip (direct link)
• Unzip and open OData_SampleData.fmp12 in FileMaker Pro.
• You can also download the Finished file from here: OData_SampleData_Axelar.zip

Required Setup Steps:

1. Add Table for Security Testing

Create a new table named omitFromOdata with the following fields (see screenshots above for field options):

Purpose:
This table is used to demonstrate and verify OData grant/revoke access via privilege sets.

2. Create a Custom Privilege Set

Create a new privilege set named OdataPrivilege (see screenshot):

• Set Records: to Custom privileges…
• Grant least privilege by default: Set all tables (including PERSON and omitFromOdata) to no access initially.
• Assign the [fmodata] extended privilege (check “Access via OData”).
• Leave other options as per your security needs.

3. Create a Limited OData Account

Beyond your Full Access account, create a new account:

• Account Name: Limited
• Privilege Set: OdataPrivilege
• Password: (set as needed)
• Activate the account.

This account will be used for all OData authentication and security behavior tests.

4. Verify Least Privilege Baseline

Disable All Table Access for OData Privilege Set

1. Go to:
   File → Manage → Security…
   • Edit the custom privilege set OdataPrivilege that will be assigned to OData-accessing accounts.
2. Go to → Data Access and Design → Records:
3. In the Custom Record Privileges dialog:
   • For each listed table (PERSON, omitFromOdata, and [Any New Table]):
     • Set View: -
     • Set Edit: -
     • Set Create: -
     • Set Delete: -
     • Set Field Access: none
4. Result:
   All tables should show: View: - Edit: - Create: - Delete: - Field Access: none as shown in the screenshot below.
5. Click OK to save the changes.

This configuration establishes a “least privilege” baseline.
No tables will be accessible via OData until you explicitly grant access in the next step.

At this stage, both PERSON and omitFromOdata should have no access for this privilege set/account.
You will then incrementally grant rights to specific tables and fields to observe OData exposure and privilege enforcement.

Test

• Log in to OData using “Limited” as account.
• Query the OData endpoint:
  https://<server>/fmi/odata/v4/
• 
• You will see the OData_SampleData.fmp12 file listed, because Odata is enabled, and you logged in with the “Limited” account that is based at OdataPrivilege Privilege Set.
• But if you click on the link,
• 
• No tables/entities will be listed because OdataPrivilege Privilege Set does not allow it.
• Query the OData $metadata endpoint:
  https://<server>/fmi/odata/v4/OData_SampleData/$metadata
• 
• Odata will return information only for Odata, Server and Schema Version used.

Step 4.0: OData/REST Vocabulary: The Mapping Table

OData Concepts and the FileMaker World

OData Term	FileMaker Equivalent
Entity	Table Occurrence (TO)
Collection	Found Set / Array of Records
Navigation Property	Relationship between TOs
Resource	Table Occurrence or Record (URL)

Remember:

• “Entity” in OData always means a Table Occurrence.
• “Collection” is a list of records in a table (the result of a query).
• “Navigation Property” refers to any relationship (join) on your relationship graph.
• “Resource” is anything you can request via the URL—table, record, relationship, or metadata.

Step 5.0: Configuring File and Account Privileges for OData

FileMaker OData API: Context-Independent Access

• OData exposes data directly from table occurrences (TOs) on the relationship graph.
• No dependency on layouts or “context” for access.
• No way to restrict access via layout (unlike Data API, PHP, or XML CWP).
• Table privilege (“No access”) is the only way to prevent exposure.
• OData always shows the raw TO structure—every field, every record, unless restricted at the privilege set.

Comparison Table

RTFM:

“OData works at the table occurrence level and is not limited by layouts. All fields and records are accessible unless restricted by the privilege set.”

Engineering Takeaway

• You must be proactive: Review and restrict access in Privilege Sets before enabling [fmodata].
• You cannot rely on hiding fields or layouts as with Data API or CWP.
• This is a fundamentally more “open”/direct integration model—handle with care!

OData Context-Independent, Table/TO-Level Exposure Control

Objective

Limit OData API exposure to only approved tables/TOs in a FileMaker file by precisely configuring privilege sets.
Example: In OData_SampleData.fmp12, only the PERSON table should be exposed, while omitFromOdata is hidden from OData clients.

Procedure

A. Edit Privilege Set for OData Accounts

1. Go to:
   File → Manage → Security…
   • Edit or create the custom privilege set that will be assigned to OData-accessing accounts.
2. Set Data Access and Design → Records:
   • Choose Custom privileges…

B. Set Table/TO-Level Access

1. For tables/TOs you want to EXPOSE via OData
   (e.g., PERSON):
   • View: yes
   • Edit/Create/Delete: As required for your use case
     (Typically “no” for read-only, “yes” if you need to allow writing)
   • Field Access:
     • Set individual fields to either “view only” or “modifiable” as needed in Custom Field Privileges
2. For tables/TOs you want to HIDE from OData
   (e.g., omitFromOdata):
   • View: no
   • Edit/Create/Delete: no
   • Field Access: none
     • This completely excludes the table from the OData entity set, $metadata, and all endpoint responses.
3. For any new table:
   • Set View to no by default unless you explicitly want new tables to be auto-exposed via OData
     (Best practice for security)

C. Test

• Log in to OData using “Limited” as account with OdataPrivilege privilege set.
• Query the OData_SampleData endpoint:
  https://<server>/fmi/odata/v4/OData_SampleData/
• 
• Now the Table/Entity PERSON will appear because OdataPrivilege privilege set allows it.
• Click on the Table/Entity name
• 
• Now you will see the Field/Recordset “Birthday” that we allowed at OdataPrivilege privilege set to show.
• Query the OData $metadata endpoint:
  https://<server>/fmi/odata/v4/OData_SampleData/$metadata
• 
• Odata now returns information not only for Odata, Server and Schema Version, but also for the PERSON Entity and the Birthday Field.

Key Principles & Gotchas

• OData exposes all TOs for which the privilege set has at least “view” access and [fmodata].
• No layouts, field-level, or layout-level restrictions apply.
  OData is not context-dependent—every field in the table/TO is visible, unless Field Access is set to Limited and the specific fields are set to no access.
• Changing table access to “no” in privilege set immediately removes the table from OData ($metadata, entity lists, queries).
• Relationship graph:
  TO must be on the graph, but “no access” still excludes it.

Dimitris Asks:

• Q: Does [fmodata] expose all tables by default?
  A: Only those that have at least “view” -> “yes” for the Table access and at least one Field set to “view only” at the Field Access.
• Q: Can you hide specific fields from OData?
  A: Yes, if Field Access is set to Limited and the specific fields are set to no access.
• Q: Does [Any New Table] default expose new tables to OData?
  A: Yes, if “view” or higher is selected. Set to “no” for best practice.

Minimum Required Privileges for Table/Field OData Exposure

To Expose a Table via OData:

• The table’s Record privileges for the relevant privilege set must be set to at least View = Yes.
• If View = No for a table (regardless of field access), OData will not expose the table/entity at all.
• If Field Access is set to none (or all fields are “no access”), OData will not expose any data/columns for that table—effectively the same as hiding the table.

To Expose a Field via OData:

• The field must be viewable (Field Access = “view only” or “modifiable”) for the privilege set.
• If all fields in a table are set to “no access,” even if View = yes for the table, the entity will be exposed in metadata but will have no accessible fields.

To Completely Hide a Table:

• Set View = no in the privilege set for that table.
• Or, set Field Access for all fields to “no access” (not recommended—better to use View = no for clarity).

Practical Table for Documentation

Key OData “Gotcha”:

OData exposure is strictly privilege-based and context-independent. Unlike Data API or Custom Web Publishing, there is no “layout” context or field mapping layer—what the privilege set can see, OData can see. Nothing more, nothing less.

Step 6.0: FileMaker-Published OData: Default Behavior

FileMaker Server’s OData implementation has specific behaviors regarding the format of data returned from each endpoint.

Default Endpoint Formats

FileMaker Always Returns HTML by Default

• To reliably get JSON from any FileMaker OData endpoint, always append:
  ?$format=json
• To reliably get XML from any FileMaker OData endpoint, always append:
  ?$format=xml

FileMaker-Published OData: Actual Default Formats (FMS 21.1.5+)

Key Clarifications:

1. HTML is the universal default for all structural endpoints in FileMaker OData.
2. JSON requires an explicit request via ?$format=json on every call.

Why FileMaker Returns HTML by Default

• Provides a human-readable documentation view of the endpoint.
• Shows all available endpoints for the service.
• Displays basic field and table information.
• Includes a built-in authentication form if credentials are missing or invalid.

Practical Tip:
Always specify the desired format in your queries when working with automation, scripting, or integration tools—especially if you need machine-readable output for JSON or XML.

To retrieve the metadata for your FileMaker OData service in JSON format, you must append ?$format=json to the metadata URL.

Syntax Example:

https://<server>/fmi/odata/v4/<ServiceName>/$metadata?$format=json

• Replace <server> with your FileMaker Server address (IP or domain).
• Replace <ServiceName> with the exact name of your hosted FileMaker file (without the .fmp12 extension).

Full Example:

https://localhost/fmi/odata/v4/OData_SampleData/$metadata?$format=json

• This will return the OData metadata for the OData_SampleData file as JSON (instead of the default HTML view).

Note:

• You can also use ?$format=xml for XML output.
• If you omit the ?$format=json parameter, FileMaker Server returns HTML by default.

Summary Table (URL patterns):

SHOW AND TELL: OData Requests and Format Switching

A. Try OData in Your Browser (Human-Readable):

https://<server>/fmi/odata/v4/

• Prompts for credentials.
• You’ll see a list of FileMaker files enabled for OData.

B. Get Table Data as HTML (Default):

https://<server>/fmi/odata/v4/<ServiceName>/<TableName>

• By default, returns a human-friendly HTML page. Good for testing, useless for code.

C. Force JSON (for scripts, code, or automation):

https://<server>/fmi/odata/v4/<ServiceName>/<TableName>?$format=json

• Returns pure JSON.
• Always append ?$format=json if you want data for automation, integration, or AI use.

D. Force XML (for legacy integrations):

https://<server>/fmi/odata/v4/<ServiceName>/<TableName>?$format=xml

• Returns XML.

E. Getting Metadata:

https://<server>/fmi/odata/v4/<ServiceName>/$metadata?$format=json

• Shows all entities (tables/TOs), fields, relationships in json