Authenticating to the Data API
FileMaker, Inc has introduced a new form of authentication called the FileMaker ID. This is an integrated sign-on system intended to provide more consistent and manageable user authentication on FileMaker Cloud. The credentials are basically a valid email address and a password. The new FileMaker Cloud exclusively uses the FileMaker ID to authenticate users.
Given this, you would expect that you can just use that same email address and password for authentication with the Data API on FileMaker Cloud. However, this is not the case, at least not in a straightforward fashion. The documentation for the FileMaker Cloud Data API indicates you need to provide an authorization header with a FileMaker ID token:
In Postman, the login request would look like this:
Using FileMaker ID for External Authentication
We need something called a FileMaker ID token in order to use the Data API. The online help for FileMaker Cloud explains how to get one. Be prepared: it is a complex multi-step process.
A Standalone Web Service
At Soliant Consulting, we wanted to simplify this process and provide you with the necessary code to make these calls. We decided to created a simple Node.js standalone web service that does all the heavy lifting for you. The web service is open source and available from our GitHub page. Because it is a standalone web service, you can integrate this authentication process into any of your automated workflows that require the use the FileMaker Cloud Data API.
When testing, you can use the Node.js web service without having to host it anywhere. Download the project from GitHub and open it in the free VS Code editor. In the Terminal window pane, navigate to the bin folder (“cd bin”) and type in “./www” to launch the web service. It will start listening on port 3000 by default.
Then you can use Postman to make a call: a POST call to the DNS name or IP address of the web service, the right port (which is 3000 in our VS Code example) and the /users endpoint. The body is a simple JSON construct with the FileMaker ID username and password that you want to use to log into the Data API.
The response includes three tokens: an accessToken, an idToken, and a refreshToken.
You can disregard the access token as it serves no purpose for logging into the Data API.
Next, copy the idToken and paste it into Postman Authorization header (making sure to prefix it with “Fmid “ (note the space). When you make the call to the Data API “sessions” endpoint to log into the Data API, you will receive a token that you can use for any subsequent calls to the Data API.
A couple of things to note:
1. With four different tokens involved here, things can get a little confusing. Let’s break down which tokens are involved where:
- On one hand, we have the FileMaker ID access token, ID token, and refresh token; on the other hand, we have the Data API login token. You need the FileMaker ID token (idToken) to log into the Data API, but you need the Data API token for any other call to the Data API.
- Your Data API token stays valid for 15 minutes after your most recent Data API call. If you do not make a call to the Data API within 15 minutes of your last call, the Data API token expires.
- At that point, you can re-use the idToken from the Soliant web service and call the Data API login again to get a new Data API token, but that will work only if that FileMaker ID idToken is less than an hour old. The FileMaker ID idToken expires one hour after it was generated.
- You can, of course, just use the web service again to get a new idToken. However, you could also use the refresh token you received in the original call. Refresh tokens are valid for 3 years.
- To use that refresh token, call the Soliant web service again, but use the /users/refresh endpoint. The JSON body to send it includes the username and the refresh token.
- The response returns a new idToken to use in a Data API login call that will give you a new Data API token.
2. All of this applies only when you are using FileMaker Cloud. It is not relevant if:
- you are hosting your files on FileMaker Cloud for AWS or with a 3rd party hosting provider.
- you have your FileMaker Server installed locally or as a cloud instance in your own AWS, Google Cloud, or Azure account.
- Download the Soliant web service from our GitHub page
- For information on how to use the Data API on non-FileMaker Cloud servers, read our other blog posts.
You can leave any suggestions and comments here on this blog post or on GitHub, and as always you can also find us on community.filemaker.com.