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.

An API token has no permissions until you assign them. The token does not inherit the permissions of the user account that created it. This is true even when an administrator account creates the token. Assign only the permissions the task needs. You can change a token's permissions later: click the token, update its permissions, and click Save. The change takes effect when you save. For the minimum permissions for common tasks, see Permissions by Task later in this article.

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. This token can list, download, and run workspaces in the Samples repository. Other tasks need different permissions. See Permissions by Task later in this article, and set the permissions for your specific use case. 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.

Permissions by Task

This section lists the minimum API token permissions confirmed for common REST API tasks. The permissions were tested against FME Flow 2026.3 with API tokens, and they apply to REST API requests. According to the FME Flow documentation, jobs submitted through FME Flow Web Services, such as Job Submitter, Data Download, and Data Streaming, also need access to the service. See Configuring Authentication for the FME Flow Web Services.

How Token Permissions Work

Permissions in Token Management work at two levels. The FME Flow documentation lists them as general permissions and individual permissions for each item. General permissions are the checkboxes on the category row, such as Access, Create, Manage, Upload, and Advanced. Jobs, Run Workspace, and Queue Control only have general permissions. Item permissions are set on individual items. Categories such as Repositories and Automations have an arrow on the right of the row. Click the arrow to open a list of items. Then select the permissions for each item, such as Run for one repository or Webhooks for one automation.

On many categories, selecting Create, Manage, or Advanced on the category row also selects Access and locks it. For example, Jobs > Manage always includes Jobs > Access. Repositories > Create and Run Workspace > Advanced work the same way. This does not apply to every permission. For example, Packages > Upload can be selected alone. Depending on the permissions you select, a dialog can also ask you to grant additional permissions for related features. See Grant Additional Permissions above.

You do not need the category Access checkbox for the tasks in this section. For Repositories and Automations, the item permissions worked with the category Access checkbox cleared. According to the FME Flow documentation, the Repositories Access checkbox controls whether users can open the Workspaces page, and only Run on the repository is needed to run a workspace.

This section writes item permissions as Category > Item > Permission, for example Repositories > Training > Run. It writes general permissions as Category > Permission, for example Jobs > Manage.

Repository Tasks

Each table lists the endpoint used in testing.

Job Tasks

Automation Tasks

Troubleshooting

A 403 error usually means the token is missing a permission. Check the tables above and add only what the task needs. A 403 message can also mean the object does not exist. For example, training returned a 403 error on a download request because the repository is named Training. In a POST /jobs request, the same mistake returned a 404 error. On the jobs endpoints, the message read: Unauthorized request by user [username] due to lack of proper permissions or the object does not exist. For 401 errors, see FME Flow Troubleshooting: REST API. For other token problems, see FME Flow Troubleshooting: Tokens.

Do not give a token All Permissions to fix a 403 error. A 403 error means FME Flow recognized the token, but the token does not have the permission for that action. Assign only the permissions the task needs. To add a missing permission, click the token in Token Management, update its permissions, and click Save. The change takes effect when you save, so you can send the request again. Avoid Select All on item lists. It selects every permission for every item in the list.

​​​​Additional Resources

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