Home / Blog / Using the Data API on FileMaker Cloud

Using the Data API on FileMaker Cloud

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:

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.

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 and the fact that FMID is all uppercase). 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.

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.

33 thoughts on “Using the Data API on FileMaker Cloud”

  1. 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.

    1. 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.

  2. 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$

    1. 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.

      1. 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 🙁

        1. 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’.

  3. 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!

    1. 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’.

  4. 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?

    1. 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

  5. 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)

    1. 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.

  6. I tried to follow the directions and I keep getting this error…
    PS D:\Downloads\FileMakerID_token-master\FileMakerID_token-master\bin> .\www
    Program ‘www’ failed to run: No application is associated with the specified file for this operationAt line:1 char:1
    + .\www
    + ~~~~~.
    At line:1 char:1
    + .\www
    + ~~~~~
    + CategoryInfo : ResourceUnavailable: (:) [], ApplicationFailedException
    + FullyQualifiedErrorId : NativeCommandFailed

    Please help

    1. Hi Michael,
      It sounds like you are trying to run this on a system that does not have Node installed yet. You can confirm that with this command from that folder: ‘npm start’
      If you don’t have Node.js installed yet you can get it from here: https://nodejs.org/en/download/, or alternatively if you intend to work with different versions of Node, you can install the Node Version Manager (nvm) with these instructions for Windows: https://docs.microsoft.com/en-us/windows/nodejs/setup-on-windows

      1. so it seems that the terminal is listening because every time I do a post. A new POST /users line pops up.

        But what I am getting from POSTMAN is:

        {
        “errors”: [
        {
        “msg”: “Invalid value”,
        “param”: “password”,
        “location”: “body”
        },
        {
        “msg”: “Invalid value”,
        “param”: “username”,
        “location”: “body”
        }
        ]
        }

        Help!

      2. Ok so I figured out that in POSTMAN it was listed as text and not JSON. Got my tokens!!!

        Thank you for your help and will definitely reach out, maybe on community, if I have any other questions.

  7. Even with the Bearer token if the claris cloud login is closed the data does not get fetched with the api. So is there any way to keep the data flowing through the api even after the claris cloud is logged out.

    1. Can you provide a bit more detail on “if the claris cloud login is closed”?
      The Data API is session-based, so if the session token expires, no calls will work anymore. Is that the scenario you are running into? If so – in your code – you can check the token’s validity and get a new one issued if it has expired so that the data flow is not interrupted.

      1. problem is data doesn’t come even bearer token generation until we should login in Claris could then only we get data if we want data we should login in Claris but due to time out Claris login closed how to fix this issues can you please help me

        1. I’m not sure I follow the “we should login in Claris” part. The whole routine is centered around *not* logging into my.claris.com at all but rather get a token from AWS Cognito and use that token to exchange for a Data API token.

          The only thing to check: make sure that the Claris ID account that you use does not have two-factor authentication turned on.

          Feel free to contact us directly or start a thread on community.claris.com, we would have to see screenshots of the full sequence to see what that Claris login looks like and where it fits into the entire flow.

          1. Christian Thygesen

            Wim,

            I agree with your comment “The whole routine is centered around *not* logging into my.claris.com at all but rather get a token from AWS Cognito and use that token to exchange for a Data API token.” However, I experience the same behaviour as Prem. If your process is executed in a “clean” environment (machine has not been logged into my.claris.com), the idToken is returned from AWS Cognito but the subsequent request for a bearer (data) token fails with error “401 Authorization Required”. However if you now log on to my.claris.com with valid Claris ID and resubmit the request for a data token it will succeed. It would be interesting if you can replicate this behaviour? I have a business partner who is trying to access our data with the API using AWSSDK.CognitoIdentity (https://www.nuget.org/packages/AWSSDK.CognitoIdentity/). They experience the same issue. I have raised this with Claris support using your blog post to provide “proof of concept” of the issue but they have not been able to help as they cannot support 3rd party software (i.e. yours).

          2. Hi Christian,
            I will try and replicate the issue. In the meantime and to get proper support from Claris, I would suggest trying the JavaScript example they have in their help docs. That way they cannot refuse support if it fails there as well.

            Best regards,
            Wim

  8. You are a life saver.

    I cannot express how pissed I am with Claris for making something they should provide (as every other API provider I have worked with does) so obscure. 5 hours, 2 extra software packages on my Mac plus your invaluable help and I finally have 255 characters of gobbledygook.

    It would be something if they were providing this technology for free but when we have paid over £1,000 i think their attitude is outrageous.

    1. Hi Chris,
      Glad that it helped you out. The extra hurdles to make this work on FM Cloud are definitely on Claris’ radar but do make sure to add your voice to the Product Ideas section, vote on any product idea that was already raised to make this better. There are a few that ask for better tokenized access. And potentially raise it as a Product Issue to make sure Claris Support is aware.
      https://community.filemaker.com/s/ideas
      https://community.filemaker.com/community/discussions/report-an-issue

      Best regards,
      Wim

  9. Hey Wim thanks so much for the work you put in on this. Quick question, how would I deploy the web service on an outside web server where I don’t have access to download and run it (bluehost)?

    1. Hi Darren,
      A couple of different options: spin up a tiny Linux instance at your preferred virtual server provider (AWS, Azure, Google Cloud, Linode…) and host it there. It doesn’t need to run on your FileMaker Server. Or you can deploy the code as an AWS Lambda function or other similar server-less deployment options.
      Best regards,
      Wim

  10. Hi Wim,

    First of all thank you so much for this guide.

    I have been able to authenticate, add data and use this from my computer locally including our local servers using the instructions above , but when I move the code to AWS it keeps giving me the error

    “Unable to log in because of security reasons.” and then I also get an email saying
    “New Claris ID sign-in attempt
    We blocked a sign-in attempt to your Claris ID account using the following unrecognised information:”

    I have checked to make sure there is no 2FA on the account used to login.
    I have tried this from different services in AWS (Lightsail, EC2, Lambda) and they all resulted in the same error.

    Do you know why this would be happening ?

    1. I believe that claris is using some sort of whitelisting-by-origin. You may be able to see something in the Access.log, Data API log or FMS event log. You can download those logs from the admin console.
      If you have a desktop on your AWS instance you can try to log into my.claris.com with a browser and then try the API call.

      FM Cloud is a bit of a black box though so your best bet for a definitive answer is to get in touch with Claris support.

      Best regards,
      Wim

Leave a Comment

Your email address will not be published. Required fields are marked *