FileMaker login to a REST API with oAuth
In Germany, REST APIs are frequently used in many industries to connect applications and systems with each other. They are particularly widespread in e-commerce, where platforms such as Shopware, Magento and WooCommerce use APIs to integrate products, orders and customer information with ERP systems or payment services such as PayPal and Klarna. APIs are also widely used in finance through Open Banking and PSD2 directives, enabling banks such as N26 and Deutsche Bank to securely transfer data to third-party providers. In logistics, APIs support shipping service providers such as DHL and Hermes with shipment tracking and the automation of shipping processes. APIs are also used in the healthcare sector to manage patient data and in public administration to digitize citizen services.
The connection to a REST API in FileMaker is a common use case for integrating data from external systems into FileMaker databases or sending data to these systems. Authentication for these REST APIs often takes place via OAuth or Token-based authentication. Below you will find detailed instructions on how this works.
FileMaker ERP with integrated
REST API interface
More information
1. Basics of the REST API connection
Before we start with the authentication, we need to call the REST API via the FileMaker function Insert from URL that is used in a script. REST APIs usually use HTTP methods how:
GET: Retrieve data from the API.POSTSend data to the API.PUTUpdate existing data.DELETEDelete data.
The main point, however, is the Registration on the API in order to be able to use these methods.
2. HTTP-Basic-Auth
One of the simplest forms of authentication is HTTP-Basic-Auth. The user name and password are entered in the Authorization-header of the HTTP request.
Example:
Set variable [ $username ; Value: "your_username" ]
Set variable [ $password ; Value: "your_password" ]
Set variable [ $url ; Value}, "https://api.example.com/resource" ]# Combine username and password, then base64-encode
Set variable [ $encodedAuth ; Value: Base64Encode ( $username & ":" & $password ) ]# Define cURL options
Set variable [ $cURLOptions ; Value:
"--header \"Authorization: Basic " & $encodedAuth & "\"" ]
# Execute API query
Insert from URL [ Selection ; Dialog: Off ; Target: $response ; URL: $url ; cURL options: $cURLOptions ]
In this example, the user name and password are converted into a Base64-encoded string and saved as Authorization header sent.
3. OAuth 2.0 Authentication
OAuth 2.0 is a standardized framework that provides a Token-based access to an API. It is available in various flows:
a) Client Credentials Flow
This flow is used when the application communicates directly with the API and no user interaction is required. Here a Access Token requested by the API.
- Request access token: To obtain an access token, a POST request is sent to the token endpoint of the API.
Set variable [ $client_id ; Value: "your_client_id" ]
Set variable [ $client_secret ; Value: "your_client_secret" ]
Set variable [ $url ; Value}, "https://auth.example.com/oauth/token" ]# Define cURL options
Set Variable [ $cURLOptions ; Value:
"--data-urlencode \"client_id=" & $client_id & "\" " &
"--data-urlencode \"client_secret=" & $client_secret & "\" " &
"--data-urlencode \"grant_type=client_credentials\"" ]# Execute API query
Insert from URL [ Selection ; Dialog: Off ; Target: $response ; URL: $url ; cURL options: $cURLOptions ]Extract # token from the JSON
Set variable [ $accessToken ; Value: JSONGetElement ( $response ; "access_token" ) ]
- API request with the access tokenOnce the token has been retrieved, it can be used for authentication with the API.
Set variable [ $api_url ; Value}, "https://api.example.com/protected_resource" ]# Define cURL options with Bearer token
Set variable [ $cURLOptions ; Value:
"--header \"Authorization: Bearer " & $accessToken & "\"" ]
# Execute API query
Insert from URL [ Selection ; Dialog: Off ; Target: $api_response ; URL: $api_url ; cURL options: $cURLOptions ]
b) Authorization Code Flow
This flow is used when the API prompts the user to authenticate and grant access to the application. The flow usually consists of the following steps:
- Redirect users to the login page of the APIA browser window opens in which the user enters their access data and grants the application authorization.
- Receive authorization code: After successful registration a Authorization Code is sent to a redirect URL.
- Exchange Authorization Code for Access TokenThe authorization code is used to request an access token.
- API request with the access token: As in the Client Credentials Flow the access token is entered in the
Authorization-header of the API request.
4. Token-based authentication (API keys)
With the Token-based authentication a static API key which is generated by the API and is used in the Authorization-header or as a URL parameter to the API.
Example:
Set variable [ $api_key ; Value: "your_api_key" ]
Set variable [ $url ; Value: "https://api.example.com/resource" ]# Define cURL options
Set variable [ $cURLOptions ; Value:
"--header \"Authorization: Bearer " & $api_key & "\"" ]# Perform the API call
Insert from URL [ Selection ; Dialog: Off ; Destination: $response ; URL: $url ; cURL options: $cURLOptions ]
Alternatively, the API key are sent as URL parameters:
Set variable [ $url ; Value}, "https://api.example.com/resource?api_key=your_api_key" ]
# Execute API query
Insert from URL [ Selection ; Dialog: Off ; Destination: $response ; URL: $url ]5. Token management
In many APIs, the Access Token after a certain time. Here a Refresh Token can be used to obtain a new Access Token without the user having to authenticate themselves again.
Set variable [ $refresh_token ; Value: "your_refresh_token" ]
Set variable [ $url ; Value}, "https://auth.example.com/oauth/token" ]
# Define cURL options for token refresh
Set variable [ $cURLOptions ; Value:
"--data-urlencode \"refresh_token=" & $refresh_token & "\" " &
"--data-urlencode \"client_id=" & $client_id & "\" " &
"--data-urlencode \"client_secret=" & $client_secret & "\" " &
"--data-urlencode \"grant_type=refresh_token\"" ]
# Execute token refresh
Insert from URL [ Selection ; Dialog: Off ; Destination: $response ; URL: $url ; cURL options: $cURLOptions ]
# Extract new access token from the JSON response
Set variable [ $new_accessToken ; ValueJSONGetElement ( $response ; "access_token" ) ]
gFM-Business Open Source FileMaker Basis-ERP
The software for the crash course
Download for free
OAuth login as FileMaker Custom Function
In order to FileMaker Custom Function that performs the login to a REST API and supports different authentication methods such as Basic Auth, OAuth2, or API keys via parameters, we can use the flexibility of FileMaker. The function should dynamically accept all relevant parameters and generate the correct format depending on the authentication type. The function requires the free FileMaker BaseElements Pluginbecause FileMaker has the function Insert from URL not supported in a separate function.
Basic idea:
The custom function should be controlled via parameters that contain the API URL, the authentication type and the necessary data such as user name, password, client ID, client secret or token. The function will then perform the authentication and send the login data to the API in the correct form.
Structure of the function:
Parameters:
apiURL: The URL of the REST API.authTypeThe type of authentication (e.g. "Basic", "OAuth2", "API-Key").usernameUser name for Basic Auth.passwordPassword for Basic Auth.clientIDClient ID for OAuth2.clientSecretClient secret for OAuth2.tokenAPI token or OAuth2 access token.extraParamsAdditional parameters for the request (e.g.grant_typefor OAuth2).
Example of the custom function:
/*
Function name: API_Login
Parameters:
apiURL (Text) - The URL of the API
authType (Text) - The authentication type (Basic, OAuth2, API key)
user (text) - user name (for Basic Auth or OAuth2)
password (Text) - Password (for Basic Auth or OAuth2)
clientID (Text) - Client ID (for OAuth2)
clientSecret (Text) - Client Secret (for OAuth2)
token (text) - Access token (for API key or OAuth2)
extraParams (Text) - Additional parameters (for OAuth2)
Returns:
Response from the API or error message
*/
SetVar ( [
//
Configuration variables
url = apiURL;
authMethod = authType;
basicAuthHeader = "Authorization: Basic " & Base64Encode(user & ":" & password);
tokenAuthHeader = "Authorization: Bearer " & token;
// Prepare data for OAuth2 Client Credentials Flow
oauthData = "client_id=" & clientID & "&client_secret=" & clientSecret & "&grant_type=client_credentials";
// Set the cURL options depending on the authentication type
cURL_Options =
If(
authMethod = "Basic"; basicAuthHeader;
authMethod = "OAuth2"; "";
authMethod = "API-Key"; tokenAuthHeader;
""
);
// Send request depending on authentication method
result = If(
authMethod = "Basic"; BE_HTTP_GET(url; cURL_Options);
authMethod = "OAuth2"; BE_HTTP_POST(url; oauthData; "Content-Type: application/x-www-form-urlencoded");
authMethod = "API-Key"; BE_HTTP_GET(url; cURL_Options); "Invalid Auth Method" ) ];
// Return the result of the API query
result
)
Functionality:
- The function checks which authentication type is used (
Basic,OAuth2,API key). - Depending on the authentication type, different cURL options generated:
- Basic Auth: Username and password are converted to a Base64-encoded string and stored in the
Authorization-header is sent. - OAuth2 Client Credentials FlowClient ID and client secret are sent in the body of the request to obtain an access token.
- API key or OAuth2 access token: The token is directly used as
Bearer-token is sent in the header.
- Basic Auth: Username and password are converted to a Base64-encoded string and stored in the
- The custom function uses HTTP Get and Put functions of the FileMaker BaseElements plugin for the server connection, because the
Insert from URL-function is not supported by FileMaker in its own functions, but only in scripts.
Example call:
API_Login(
"https://api.example.com/login",
"Basic",
"myUsername",
"myPassword",
"",
"",
""
)
Expansion options:
- Error handlingThe function can be extended to recognize error codes from the API and return corresponding messages.
- Token renewalIf an access token expires, the function can be extended so that it automatically requests a new token.
- Support for further OAuth2 flows: The code could be extended so that Authorization Code Flow and Password Grant Flow be supported.
This custom function provides a flexible way to integrate different authentication mechanisms with REST APIs in FileMaker and can be easily customized to meet specific requirements.
Four FileMaker ERP platforms for optimal operating processes to buy and rent.
Request information Frequently asked questions about FileMaker and REST-API with oAuth
- What is OAuth and why is it used for logging in to a REST API?
- OAuth is an open standard protocol that is used for the secure authorization of API access. It enables applications such as FileMaker to access protected resources of an API without users having to enter their access data directly. OAuth provides a secure way to authorize without sharing sensitive credentials.
- How does the OAuth flow work when logging in to a REST API?
- The OAuth flow usually begins with FileMaker sending a request to an authorization server to obtain a token. This token is then used to access the REST API. There are different OAuth flow types, but the most common is the Authorization Code Flow, where the user is authenticated via a login page of the API and FileMaker then receives an access token.
- What information do I need to connect FileMaker to a REST API via OAuth?
- You need the client ID, client secret, redirect URI and the authorization and token URLs of the API. You usually receive this information from the API provider after you have registered an application. FileMaker uses this data to authenticate itself via the OAuth process.
- How do I authenticate FileMaker with OAuth against a REST API?
- First you need to initialize the OAuth process by making an authorization request via FileMaker using the Insert from URL function. After successful authorization, you will receive an access token that you can use in further API requests to access protected resources.
- How do I save the OAuth token in FileMaker for later API calls?
- The received token is usually stored in a field in FileMaker to use it for future API calls. Tokens often have a limited lifetime and you need to renew them regularly by requesting a new token.
- What happens when the OAuth token expires?
- If the access token expires, you will receive an error from the API (e.g. HTTP status code 401 "Unauthorized"). In this case, you must use the refresh token to obtain a new access token without the user having to log in again. The refresh token is provided during the original OAuth process.
- How do I get a refresh token in FileMaker?
- When you go through the first OAuth flow, you not only receive an access token, but also a refresh token. This refresh token can be stored in FileMaker. Once the access token expires, a new access token can be requested by using the refresh token without re-authenticating the user.
- What security precautions do I need to take when using OAuth in FileMaker?
- You should ensure that sensitive data such as Client Secret, Access Token and Refresh Token are stored securely. Use encrypted fields in FileMaker and secure the database with the right access controls. You should also ensure that you use HTTPS for data traffic with the API.
- Can FileMaker automatically request a new token when the old one has expired?
- Yes, you can set up a script in FileMaker that checks the status code of an API request. If a 401 error is returned due to an expired token, the script can automatically request a new token with the saved refresh token and resend the request.
- What do I do if the REST API uses OAuth 2.0, but FileMaker only supports basic authentication?
- If an API requires OAuth 2.0, you must fully integrate the OAuth flow into FileMaker. Basic authentication will not be enough. However, you can create a script in FileMaker that automates the entire OAuth process (authorization request, token storage, token renewal) and ensures that all API calls are made with the appropriate tokens.
Summary
FileMaker offers the option of addressing REST APIs and using different authentication mechanisms such as OAuth, Basic Auth and Token-based authentication support. Through the use of Insert from URL and cURL options you can handle complex authentication processes and ensure that your FileMaker solutions communicate seamlessly with external systems. As soon as the login to the REST API is error-free, you can call the desired endpoints of your API and process the supplied data.
