API keys and authentication

Authentication credentials help prevent unauthorized access to your Robility flow server, flows, and services connected through components.

There are three types of credentials that you use in Robility flow:

1. Robilityflow API keys: For authentication with the Robility flow API and authorizing server-side Robility flow actions like running flows and uploading files.
2. Component API keys: For authentication between Robility flow and a service connected through a component, such as a model provider or third-party API.
3. Authentication environment variables: These environment variables configure how Robility flow handles user authentication and authorization.

Robility flow API keys

Robility Flow API keys allow you to interact with the platform programmatically, offering the same permissions as your user account. This means:

1. Your API key can access only your own flows, components, and data.
2. It cannot access other users’ resources.
3. The key represents the user who created it, if created by a superuser, it inherits superuser privileges.
4. Anyone with a superuser API key can perform privileged actions such as user and flow management via the Robility Flow API.

In single-user environments, you are always a superuser, and your Robility flow API keys always have superuser privileges.

In multi-user environments, users who aren’t superusers cannot use their API keys to access other users’ resources. You must start your Robility flow server with authentication enabled to allow user management and creation of non-superuser accounts.

Authentication and Access

Most API endpoints in Robility Flow require an API key, even if AUTO_LOGIN is enabled.

Create a Robility Flow API Key

You can generate an API key using the Robility Flow application, depending on your server configuration:

Using the Robility Flow UI

1. Click your profile icon in the Robility Flow header and select Settings.
2. Navigate to Robility Flow API Keys and click Add New.
3. Provide a name for your API key and click Create API Key.
4. Copy the generated key and store it in a secure location.

Using the Robilityflow CLI

If you’re serving your flow with --backend-only=true, you can’t create API keys in your Robility flow Settings because the frontend isn’t running. In this case, you must create API keys with the Robility flow CLI.

1. Recommended: Start your Robility flow server with authentication enabled.

This configuration is recommended for security reasons to prevent unauthorized API key and superuser creation, especially in production environments.

However, if authentication isn’t enabled (ROBILITYFLOW_AUTO_LOGIN=True), all users are effectively superusers, and they can create API keys with the Robility flow CLI.

2. Create an API key with robilityflow api-key: uv run robilityflow api-key

All API keys created with the Robility flow CLI have superuser privileges because the command requires superuser authentication, and Robility flow API keys adopt the privileges of the user who created them.

Authenticating API Requests

To authenticate your API requests, include the API key in the HTTP header:

Authorization: <Your-API-Key>

Note: API keys grant access only to the flows and components associated with the user who generated the key.

curl -X POST \

  “http://ROBILITY FLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false” \

  -H ‘Content-Type: application/json’ \

  -H ‘x-api-key: ROBILITY FLOW_API_KEY’ \

  -d ‘{“inputs”: {“text”:””}, “tweaks”: {}}’

Query parameter

To pass the API key as a query parameter:

curl -X POST \

  “http://ROBILITYFLOW_SERVER_ADDRESS/api/v1/run/FLOW_ID?x-api-key=ROBILITYFLOW_API_KEY” \

  -H ‘Content-Type: application/json’ \

  -d ‘{“inputs”: {“text”:””}, “tweaks”: {}}’

For more information about forming Robility flow API requests, see Get started with the Robility flow API and Trigger flows with the Robility flow API.

Revoke a Robility Flow API Key

To revoke an existing API key, delete it through the Robility Flow user interface:

1. In the Robility Flow UI, click your profile icon in the header and select Settings.
2. Navigate to Robility Flow API Keys.
3. Select the key(s) you want to remove and click Delete.

Once deleted, the key is immediately invalidated and can no longer be used to access the API.

Component API Keys in Robility Flow

Component API keys authorize access to external services that are called by components in your flows, such as model providers, databases, or third-party APIs. These aren’t Robility flow API keys or general application credentials.

In Robility flow, you can store component API keys in global variables in your Settings or import them from your Robilityflow .env file. When creating global variables, use the Credential type for secure handling of sensitive information. For more information, see Global variables.

You create and manage component API keys within the service provider’s platform. Robilityflow only stores the encrypted key value or a secure reference to a key stored elsewhere; it doesn’t manage the actual credentials at the source. This means that deleting a global variable from Robilityflow doesn’t delete or invalidate the actual API key in the service provider’s system. You must delete or rotate component API keys directly using the service provider’s interface or API.

Authentication environment variables

This section describes the available authentication configuration variables.

ROBILITYFLOW_AUTO_LOGIN

This variable controls whether authentication is required to access your Robility flow server, including the visual editor and API:

a. If ROBILITYFLOW_AUTO_LOGIN=False, automatic login is disabled. Users must sign in to the visual editor and use a Robility flow API key for Robility flow API requests. If false, you must also set ROBILITYFLOW_SUPERUSER and ROBILITYFLOW_SUPERUSER_PASSWORD.

b. If ROBILITYFLOW_AUTO_LOGIN=True, Robility flow bypasses authentication for the visual editor and API requests. All users can access the same environment without password protection. If you don’t have user management enabled, all users are effective superusers.

Robility flow doesn’t allow users to simultaneously edit the same flow in real time. If two users edit the same flow, Robility flow saves only the work of the most recent editor based on the state of that user’s workspace. Any changes made by the other user in the interim are overwritten.

AUTO_LOGIN and API authentication in version 1.5 and later

In Robility flow versions 1.5 and later, most API endpoints require a Robility flow API key, even when AUTO_LOGIN is true. The only exceptions are the MCP endpoints /v1/mcp, /v1/mcp-projects, and /v2/mcp, which never require authentication.

ROBILITYFLOW_AUTO_LOGIN and ROBILITYFLOW_SKIP_AUTH_AUTO_LOGIN options

ROBILITYFLOW_ENABLE_SUPERUSER_CLI

Controls the availability of the Robility flow superuser command in the Robility flow CLI. The default is true, but false is recommended to prevent unrestricted superuser creation. For more information, see Robility flow superuser.

ROBILITYFLOW_SUPERUSER & ROBILITYFLOW_SUPERUSER_PASSWORD

These variables specify the username and password for the Robility flow server’s superuser.

ROBILITYFLOW_SUPERUSER=administrator

ROBILITYFLOW_SUPERUSER_PASSWORD=securepassword

They are required if ROBILITYFLOW_AUTO_LOGIN=False. Otherwise, they aren’t relevant.

If required and not set in when you start a Robility flow server with authentication enabled, then the default values are Robility flow and Robility flow for system auto-login behavior. These defaults don’t apply when using the Robility flow CLI command Robility flow superuser.

ROBILITYFLOW_SECRET_KEY

This environment variable stores a secret key used for encrypting sensitive data like API keys. Robility flow uses the Fernet library for secret key encryption.

If no secret key is provided, Robility flow automatically generates one.

However, you should generate and explicitly set your own key in production environments. This is particularly important for multi-instance deployments like Kubernetes to ensure consistent encryption across instances.

To generate a secret encryption key for ROBILITYFLOW_SECRET_KEY, do the following:

1. Run the command to generate and copy a secret to the clipboard.

a. macOS or Linux: Generate a secret key and copy it to the clipboard:

python3 -c “from secrets import token_urlsafe; print(f’ROBILITYFLOW_SECRET_KEY={token_urlsafe(32)}’)” | pbcopy

Linux: Generate a secret key and copy it to the clipboard:

python3 -c “from secrets import token_urlsafe; print(f’ROBILITYFLOW_SECRET_KEY={token_urlsafe(32)}’)” | xclip -selection clipboard

Unix: Generate a secret key and print it to the terminal to manually copy it:

python3 -c “from secrets import token_urlsafe; print(f’ROBILITYFLOW_SECRET_KEY={token_urlsafe(32)}’)”

2. Paste the value into your .env file:

ROBILITYFLOW_SECRET_KEY=dBuu…2kM2_fb

b. Windows:

Generate a secret key and copy it to the clipboard:

python -c “from secrets import token_urlsafe; print(f’ROBILITYFLOW_SECRET_KEY={token_urlsafe(32)}’)”

Generate a secret key and print it to the terminal to manually copy it:

# Or just print
python -c “from secrets import token_urlsafe; print(f’ROBILITYLOW_SECRET_KEY={token_urlsafe(32)}’)”

Paste the value into your .env file:

ROBILITYFLOW_SECRET_KEY=dBuu…2kM2_fb

ROBILITYFLOW_NEW_USER_IS_ACTIVE

ROBILITYFLOW_NEW_USER_IS_ACTIVE

When ROBILITYFLOW_NEW_USER_IS_ACTIVE=False (default), a superuser must explicitly activate a new user’s account before they can sign in to the visual editor. The superuser can also deactivate a user’s account as needed.

When ROBILITYFLOW_NEW_USER_IS_ACTIVE=True, new user accounts are automatically activated.

ROBILITYFLOW_NEW_USER_IS_ACTIVE=False

Only superusers can manage user accounts for a Robility flow server, but user management only matters if your server has authentication enabled. For more information, see Start a Robility flow server with authentication enabled.

Start a Robility flow server with authentication enabled

This section shows you how to use the authentication environment variables to deploy a Robility flow server with authentication enabled. This involves disabling automatic login, setting superuser credentials, generating a secret encryption key, and enabling user management.

This configuration is recommended for any deployment where Robility flow is exposed to a shared or public network, or where multiple users access the same Robility flow server.

With authentication enabled, all users must sign in to the visual editor with valid credentials, and API requests require authentication with a Robility flow API key. Additionally, you must sign in as a superuser to manage users and create a Robility flow API key with superuser privileges.

Start the Robility flow server

1. Create a .env file with the following variables:

ROBILITYFLOW_AUTO_LOGIN=False

ROBILITYFLOW_SUPERUSER=

ROBILITYFLOW_SUPERUSER_PASSWORD=

ROBILITYFLOW_SECRET_KEY=

ROBILITYFLOW_NEW_USER_IS_ACTIVE=False

ROBILITYFLOW_ENABLE_SUPERUSER_CLI=False

Your .env file can have other environment variables. This example focuses on authentication variables.

2. Set ROBILITYFLOW_SUPERUSER and ROBILITYFLOW_SUPERUSER_PASSWORD to your desired superuser credentials.

For a one-time test, you can use basic credentials like administrator and password. Strong, securely stored credentials are recommended in genuine development and production environments.

3. Recommended: Generate and set a ROBILITYFLOW_SECRET_KEY for encrypting sensitive data.

If you don’t set a secret key, Robility flow generates one automatically, but this isn’t recommended for production environments.

For instructions on generating at setting a secret key, see ROBILITYFLOW_SECRET_KEY.

4. Save your .env file with the populated variables. For example:

ROBILITYFLOW_AUTO_LOGIN=False

ROBILITYFLOW_SUPERUSER=administrator

ROBILITYFLOW_SUPERUSER_PASSWORD=securepassword

ROBILITYFLOW_SECRET_KEY=dBuu…2kM2_fb

ROBILITYFLOW_NEW_USER_IS_ACTIVE=False

ROBILITYFLOW_ENABLE_SUPERUSER_CLI=False

5. Start Robility flow with the configuration from your .env file:

uv run Robility flow run –env-file .env

Starting Robility flow with a .env file automatically authenticates you as the superuser set in ROBILITYFLOW_SUPERUSER and ROBILITYFLOW_SUPERUSER_PASSWORD. If you don’t explicitly set these variables, the default values are Robility flow and Robility flow for system auto-login.

6. Verify the server is running. The default location is http://localhost:7860.

Next, you can add users to your Robility flow server to collaborate with others on flows.

Manage users as an administrator

1. To complete your first-time login as a superuser, go to http://localhost:7860/login.

If you aren’t using the default location, replace localhost:7860 with your server’s address.

2. Log in with the superuser credentials you set in your .env (ROBILITYFLOW_SUPERUSER and ROBILITYFLOW_SUPERUSER_PASSWORD).

3. To manage users on your server, navigate to /admin, such as http://localhost:7860/admin, click your profile icon, and then click Admin Page.

As a superuser, you can add users, set permissions, reset passwords, and delete accounts.

4. To add a user, click New User, and then complete the user account form:

5. Enter a username and password.

6. To activate the account immediately, select Active. Inactive users cannot sign in or access flows they created before becoming inactive.

7. Deselect Superuser if you don’t want the user to have full administrative privileges.

8. Click Save. The new user appears in the Admin Page.

9. To test the new user’s access, sign out of ROBILITYFLOW, and then sign in with the new user’s credentials.

Try to access the /admin page. You are redirected to the /flows page if the new user isn’t a superuser.