BlogFileMaker

Using the Data API on FileMaker Cloud

By November 6, 2019 14 Comments

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.

Screenshot of login using FileMaker ID

Figure 1 – Logging into FileMaker Pro with a FileMaker ID

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:

Screenshot of the FileMaker Cloud Data API documentation

Figure 2 – The FileMaker Cloud Data API documentation

In Postman, the login request would look like this:

Screenshot of the postman headers for a Data API login call

Figure 3 – Postman headers for a Data API login call

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.

In essence it comes down to making the authentication call directly to Amazon Cognito, which is the underlying mechanism that drives FileMaker ID. The help article includes example JavaScript code to make such an authentication call.

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.

Screenshot of starting the web service in VS Code

Figure 4 – Starting the web service in VS Code

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.

Screenshot of the response of a call to the web service

Figure 5 – Response of a call to the web service

Tokens

The response includes three tokens: an accessToken, an idToken, and a refreshToken.

According to the Amazon AWS documentation these tokens represent:

  • The ID Token contains claims about the identity of the authenticated user such as name and email.
  • The Access Token grants access to authorized resources.
  • The Refresh Token contains the information necessary to obtain a new ID or access token.

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.

Screenshot of the response of a Data API login call

Figure 6 – Response of a Data API login call

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.
Screenshot of the postman call to the web service using the refresh token

Figure 7 – Postman call to the web service using 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.

Resources

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.

Wim Decorte

Wim Decorte

Wim is a Senior Technical Solution Architect at Soliant. He is a FileMaker 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17 and 18 Certified FileMaker Developer and the author of numerous Tech Briefs and articles on FileMaker Server. Wim is one of the very few multiple FileMaker Excellence Award winners and was most recently awarded the FileMaker Community Leader of the Year award at the 2015 FileMaker Developer Conference. He is also a frequent speaker at the FileMaker Developer Conference and at FileMaker Developer groups throughout the world. In addition to being a renowned expert on FileMaker Server, Wim also specializes in integrating FileMaker with other applications and systems. His pet project is the open source fmDotNet connector class that he created.

14 Comments

  • Avatar Sky Willmott says:

    Hello, thanks for these details. I have downloaded Visual Studio Code and the project files from Github. I open the project in Visual Studio Code and start a new terminal window, and then type ‘cd bin’ and then ‘./www’ as instructed but terminal just comes back with ‘env: node: No such file or directory’. Any ideas what I might be doing wrong?

    Screenshot of my Visual Studio Code session here: https://www.icloud.com/iclouddrive/0zelLxmPFB2tTT4twzB_klh-w#Screenshot_2020-01-29_at_03.38

    Currently absolutely stumped on how to authorise with FM Cloud Data API, so any help much appreciated.

    • Wim Decorte Wim Decorte says:

      It looks like you do not have node.js installed on that machine. That sample web service runs on node.js so go grab it from nodejs.org first and then try to run it. If you don’t want to add things to your OS then perhaps use a small Linux VM instead.

  • Avatar Sébastien says:

    Hello Wim,
    Please find below what I am getting from the terminal window pane in VS Code…
    From your VS Code screenshot, it seems like the only difference from what you can download from GitHub is that the node_modules repo is missing.

    Tatai:FileMakerID_token seb$ cd bin
    Tatai:bin seb$ ./www
    internal/modules/cjs/loader.js:985
    throw err;
    ^

    Error: Cannot find module ‘http-errors’
    Require stack:
    – /Users/seb/Documents/GitHub/FM/FileMakerID_token/app.js
    – /Users/seb/Documents/GitHub/FM/FileMakerID_token/bin/www
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:982:15)
    at Function.Module._load (internal/modules/cjs/loader.js:864:27)
    at Module.require (internal/modules/cjs/loader.js:1044:19)
    at require (internal/modules/cjs/helpers.js:77:18)
    at Object. (/Users/seb/Documents/GitHub/FM/FileMakerID_token/app.js:1:19)
    at Module._compile (internal/modules/cjs/loader.js:1158:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1178:10)
    at Module.load (internal/modules/cjs/loader.js:1002:32)
    at Function.Module._load (internal/modules/cjs/loader.js:901:14)
    at Module.require (internal/modules/cjs/loader.js:1044:19) {
    code: ‘MODULE_NOT_FOUND’,
    requireStack: [
    ‘/Users/seb/Documents/GitHub/FM/FileMakerID_token/app.js’,
    ‘/Users/seb/Documents/GitHub/FM/FileMakerID_token/bin/www’
    ]
    }
    Tatai:bin seb$

    • Wim Decorte Wim Decorte says:

      HI Sébastien,
      From inside VS Code, in Terminal, make sure that you are inside the project and then type in “npm install” which will collect all the necessary Node packages and install them.

      • Avatar Sébastien says:

        Thank you Wim for sorting me out !
        Things are working (sort of) now…
        This is the JSON response I am getting with the code 200 !?!
        {
        “user”: “xxxxxxxxxx”,
        “tokens”: “”,
        “error”: “MFA required”
        }
        This seems like a new “feature” of FileMaker Cloud 2.18.1.1056 🙁

        • Wim Decorte Wim Decorte says:

          I’ve tested the web service with FM Cloud 2.18.1056 and it works fine. In my.filemaker.com, go to your profile and turn off the MFA setting. Or if you have room in your FM Cloud subscription for an additional licensed account, create an account and set it to not use MFA and treat it as a ‘service account’.

  • Hello Wim!
    I have a trouble.

    I get this answer:
    {
    “user”: “email@clarisid.com”,
    “tokens”: “”,
    “error”: {
    “code”: “NotAuthorizedException”,
    “name”: “NotAuthorizedException”,
    “message”: “Unable to login because of security reasons.”
    }
    }

    And after two or three attempts, I get an e-mail of Claris, requesting me an authorization of my Location.

    I’m in mexico, so, I need to be connected from USA to get no errors?

    Thanks for your guide!

    • Wim Decorte Wim Decorte says:

      Most likely that is because that Claris ID is set up for two-factor authentication. Log in to my.filemaker.com with that Claris ID, click on the email address on the top right in the black banner and choose ‘Profile’. Scroll down to the Security section and turn off the ‘two-step verification’.

  • I have a question.
    How can I deploy your WebService on a Windows Server? I have never installed a webService and I don’t know where to start.
    What I need to do that?

    • Wim Decorte Wim Decorte says:

      Hi Juan,

      The ‘how-to’ would take more space than we have here; I’ll write it up in separate blog post.

      Best regards,
      Wim

  • Avatar Binu Alexander says:

    Hi Wim,
    I have got the Node service running on 127.0.0.1:3000, but when I run the POST method, and supply the username and password in the body, this is the error I get, and I am not able to move forward.

    Unexpected token = in JSON at position 17
    400
    SyntaxError: Unexpected token = in JSON at position 17
    at JSON.parse ()
    at parse (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/body-parser/lib/types/json.js:89:19)
    at /Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/body-parser/lib/read.js:121:18
    at invokeCallback (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/raw-body/index.js:224:16)
    at done (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/raw-body/index.js:213:7)
    at IncomingMessage.onEnd (/Users/alexander/Code/NodeJS/Claris/FileMakerID_token/node_modules/express/node_modules/raw-body/index.js:273:7)
    at IncomingMessage.emit (events.js:327:22)
    at endReadableNT (_stream_readable.js:1220:12)
    at processTicksAndRejections (internal/process/task_queues.js:84:21)

    • Wim Decorte Wim Decorte says:

      Hi,

      Unfortunately that doesn’t give us enough information to troubleshoot. This could be one of two issues:
      1) when you installed the micro service, did you do an “npm install” to load all the referenced modules?
      2) assuming that you did, it looks like the JSON that you are sending is malformed and not recognized as JSON. Pay particular attention to quotes and commas.

      Feel free to create a post on community.claris.com and reference me by name, and post some screenshots of what you are sending.

Leave a Reply

Need to adjust your business processes quickly? We're helping clients use technology to keep their teams productive and running smoothly in these times of uncertainty. Our team can guide yours if you need help in these areas.

Talk to a Consultant