Authorization in the FME Flow REST API | Token Management

Introduction

Security is always a significant consideration when working with any online service. The REST API works with security in two ways: authorization and authentication. Authentication proves that the user is who they say they are. Authorization verifies that the user is authorized to make the call.

Most calls to FME Flow (formerly FME Server) require authorization. The REST API uses tokens to prove the user is permitted to make the call to the server. A token is a string of encrypted information that is sent between the client and the server. Token Security will not be as secure as other methods, as the security of the system depends on controlling access to the tokens. 

While creating tokens to use with the REST API, try to limit the permissions the token is given. If the token is exposed, there will be limited access to the rest of the server. 

Types of Tokens

There are two types of tokens in FME Flow: API and Session. 

API Tokens

API Tokens should be used to provide applications with unauthenticated access to components in FME Flow. One example of using an API Token is if you would like to share your workspace either through an FME Flow App or a Webhook URL. Depending on what method you choose, you may need to generate the token separately through the Token Management page, or the token creation may be included as a step in the share workspace process. 
From the Token Management page, API Tokens can be enabled, disabled, duplicated, or removed, and all expired tokens will also be listed.

Session Tokens

Session Tokens are assigned all the permissions that the user who created them has. These should be short-lived and are designed to be used by FME Flow's internal services and for testing purposes. Session tokens have fewer actions available than API tokens: they cannot be duplicated and once expired, these cannot be re-activated.

It is possible this list may expand in the future.

These tokens should not be used in applications or shared between users. Expired Session Tokens have a clean-up task and are removed by default once they are a week old.

Obtaining API Tokens

API Tokens can be obtained manually via the Token Management page. These tokens can be downloaded and used in external applications. Additionally, tokens can be automatically created when building an FME Flow App or creating a webhook. How to manually create a token will be outlined below. 

Obtaining a Token Through the Token Management Page

1. Log into FME Flow
Open the FME Flow Web Interface and log into an account with permissions to create a new user and tokens. 

2. Open the Tokens Management Page
In the top-right corner, click on the user icon, and from the drop-down select Manage Tokens. 

Depending on your level of permissions, you may see API Tokens, Session Tokens, All Tokens as tabs across the top of the Token Management page. For this demo, we will be focusing on API tokens. To learn more about the other options, see the documentation.

3. Create a New Token - Metadata
In the API Token section, click on New to create a new token. 

On the Create New API Token page, enter the following parameters:

• Token Name: REST API Demo
• Description: Token to be used during training
• Enabled: On
• Expiration: 1 week
• All Permissions: Off

4. Assign Permissions to Token
Next, we need to assign permissions to the token. We can use this token for the REST API training course or most of the REST API articles on the Knowledge Base. If you have a specific use case, please set your permissions accordingly. To learn more about what each permission includes, see the documentation: expand To Create an API Token > About permissions in FME Flow, then expand the permission of interest. 

Once the permissions have been set, click Create. 

5. Download Token
Once the token has been created, you will see a page with your token visible. This is the only time you’ll be able to see this token within FME Flow. To access it later, click the Download button to download the token. 


The token is downloaded in an unsecured text (.txt) file. 

Obtaining a Token Through FME Flow REST API V4

Tokens can be created using the FME Flow REST API by making a POST request. Within the request body, either secondsToExpiry or expiration must be specified, but not both. There are no additional parameters required. The request URL is http://<yourFMEFlowHost>/fmeapiv4/tokens, where <yourFMEFlowHost> is the specific name of your FME Flow. 

Please see the sample request body below:

{
 "name": "string",
 "description": "string",
 "ownerID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "enabled": true,
 "customPermissions": true,
 "secondsToExpiry": 0,
 "expiration": "2025-07-29T20:44:40.785Z"
}

To test this API call, you can access the API documentation through your FME Flow web UI. On the homescreen, click the question mark icon at the top right corner and select REST API.

Select API Endpoints, and scroll to the Tokens header. Click the arrow to open all the token endpoints and select POST /tokens. Next, click Try it out, and you'll be prompted to log in to your FME Flow. After you enter your credentials, click Execute, and the responses will be shown below.

Grant Additional Permissions

There are many intertwined features within FME Flow that rely on permissions for other features to work, such as Automations. After clicking OK, depending on which permissions were set, a pop-up dialog may appear asking to grant additional permissions for other features. When creating the token, it is important to evaluate whether or not the token user will actually need access to these features.

Using a Token

Tokens can be included in the authorization header or in the query parameter

Authorization Header

Including the token inside the Request Header is the preferred method. This is because the token will be hidden inside the call. 

The name of the header would be Authorization, and the Value would be:

fmetoken token=<yourTOKEN>

Replace everything after the = with your token that you downloaded from FME Flow. 

Query Parameter

You may include the token right in the Request URL of the call. This is a quick and easy way to use a call that requires a token.

http://<yourServerHost>/fmeinfo/general?fmetoken=<yourTOKEN>

However, this is not recommended because the token will be visible in the URL.

​​​​Additional Resources

Tutorial: Getting Started with APIs
REST API Documentation
Managing Security Tokens Documentation