Skip to main content

API keys and authentication

warning

Never expose SkillFlaw ports directly to the internet without proper security measures. Set explicit SKILLFLAW_SUPERUSER and SKILLFLAW_SUPERUSER_PASSWORD values, prefer SKILLFLAW_SECRET_KEY_FILE or set SKILLFLAW_SECRET_KEY explicitly, and deploy your SkillFlaw server behind a reverse proxy. For more information, see Configure a secured SkillFlaw server.

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

There are three types of credentials that you use in SkillFlaw:

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

SkillFlaw API keys​

You can use SkillFlaw API keys to interact with SkillFlaw programmatically.

By default, most SkillFlaw API endpoints, such as /api/v1/run/$FLOW_ID, require authentication with a SkillFlaw API key.

SkillFlaw validates API keys against keys stored in the database, but you can configure SkillFlaw to validate API keys against an environment variable instead. For more information, see SKILLFLAW_API_KEY_SOURCE.

To require API key authentication for flow webhook endpoints, use the SKILLFLAW_WEBHOOK_AUTH_ENABLE environment variable. To configure authentication for SkillFlaw MCP servers, see Use SkillFlaw as an MCP server.

SkillFlaw API key permissions​

A SkillFlaw API key adopts the privileges of the user who created it. This means that API keys you create have the same permissions and access that you do, including access to your flows, components, and SkillFlaw database. A SkillFlaw API key cannot be used to access resources outside of your own SkillFlaw server.

In single-user environments, you are always a superuser, and your SkillFlaw 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. Superusers can only run their own flows, and cannot run flows owned by other users. You must configure your SkillFlaw server for secure access to allow superusers to manage users and create non-superuser accounts.

Create a SkillFlaw API key​

You can generate a SkillFlaw API key in your SkillFlaw Settings.

The retained skillflaw api-key CLI command no longer creates API keys. It only reports that unauthenticated CLI API key creation is unsupported.

  1. In the SkillFlaw header, click your profile icon, and then select Settings.
  2. Click SkillFlaw API Keys, and then click Add New.
  3. Name your key, and then click Create API Key.
  4. Copy the API key and store it securely.

Use a SkillFlaw API key​

To authenticate SkillFlaw API requests, pass your SkillFlaw API key in an x-api-key header or query parameter.


_10
curl -X POST \
_10
"http://$SKILLFLAW_SERVER_ADDRESS/api/v1/run/$FLOW_ID?stream=false" \
_10
-H "Content-Type: application/json" \
_10
-H "x-api-key: $SKILLFLAW_API_KEY" \
_10
-d '{"inputs": {"text":""}, "tweaks": {}}'

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

Track API key usage​

By default, SkillFlaw tracks API key usage through total_uses and last_used_at records in your SkillFlaw database.

To disable API key tracking, set SKILLFLAW_DISABLE_TRACK_APIKEY_USAGE=True in your SkillFlaw environment variables. This can help avoid database contention during periods of high concurrency.

Revoke an API key​

To revoke and delete an API key, do the following:

  1. In the SkillFlaw header, click your profile icon, and then select Settings.
  2. Click SkillFlaw API Keys.
  3. Select the keys you want to delete, and then click Delete.

This action immediately invalidates the key and prevents it from being used again.

Component API keys​

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 SkillFlaw API keys or general application credentials.

In SkillFlaw, you can store component API keys in global variables in your Settings or import them from your runtime environment. For more information, see Global variables.

You create and manage component API keys within the service provider's platform. SkillFlaw 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 SkillFlaw 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.

For added security, you can set SKILLFLAW_REMOVE_API_KEYS=True to omit API keys and tokens from flow data in your SkillFlaw database. Additionally, when exporting flows, you can choose to omit API keys from the exported flow JSON.

Authentication environment variables​

This section describes the available authentication configuration variables.

You can use the .env.example file from the project source as a template for your own .env file.

AUTO_LOGIN settings​

The legacy auto-login compatibility variables used by pre-1.6 releases no longer apply to current SkillFlaw releases. Use the settings below to configure bootstrap credentials, sign-in behavior, API key validation, webhook authentication, and cookie behavior instead.

SKILLFLAW_ENABLE_SUPERUSER_CLI​

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

SKILLFLAW_SUPERUSER and SKILLFLAW_SUPERUSER_PASSWORD​

These variables specify the username and password for the SkillFlaw server's bootstrap superuser.


_10
SKILLFLAW_SUPERUSER=administrator
_10
SKILLFLAW_SUPERUSER_PASSWORD=securepassword

If these variables are not set, SkillFlaw falls back to the default values skillflaw and skillflaw, which are insecure and should be overridden in any real environment. These defaults don't apply when using the SkillFlaw CLI command skillflaw superuser.

SKILLFLAW_SECRET_KEY​

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

If no secret key is provided, SkillFlaw 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 SKILLFLAW_SECRET_KEY, do the following:

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

    • macOS: Generate a secret key and copy it to the clipboard:


      _10
      python3 -c "from secrets import token_urlsafe; print(f'SKILLFLAW_SECRET_KEY={token_urlsafe(32)}')" | pbcopy

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


      _10
      python3 -c "from secrets import token_urlsafe; print(f'SKILLFLAW_SECRET_KEY={token_urlsafe(32)}')" | xclip -selection clipboard

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


      _10
      python3 -c "from secrets import token_urlsafe; print(f'SKILLFLAW_SECRET_KEY={token_urlsafe(32)}')"

  2. Paste the value into your .env file:


    _10
    SKILLFLAW_SECRET_KEY=dBuu...2kM2_fb

SKILLFLAW_NEW_USER_IS_ACTIVE​

When SKILLFLAW_NEW_USER_IS_ACTIVE=False (default), accounts created by superusers are inactive by default and must be explicitly activated before users can sign in to the visual editor. The superuser can also deactivate a user's account as needed.

When SKILLFLAW_NEW_USER_IS_ACTIVE=True, accounts created by superusers are automatically activated.


_10
SKILLFLAW_NEW_USER_IS_ACTIVE=False

Only superusers can manage user accounts for a SkillFlaw server. For more information, see Configure a secured SkillFlaw server.

SKILLFLAW_API_KEY_SOURCE​

This variable controls how SkillFlaw validates API keys.

ValueDescription
db (default)Validates API keys against SkillFlaw API keys stored in the database. This is the standard behavior where users create and manage API keys through the SkillFlaw UI or CLI.
envValidates API keys against the SKILLFLAW_API_KEY environment variable. Useful for Kubernetes deployments, CI/CD pipelines, or any environment where you want to inject a pre-defined API key without database configuration.

By default, SkillFlaw validates the x-api-key header against the SkillFlaw database with SKILLFLAW_API_KEY_SOURCE=db. When using database-based validation, you can create multiple keys with per-user permissions, track usage, and manage keys through the SkillFlaw UI or CLI.

When SKILLFLAW_API_KEY_SOURCE=env, SkillFlaw validates the x-api-key header against the value of the SKILLFLAW_API_KEY environment variable. This means SkillFlaw runs securely in stateless environments, such as with LFX or Kubernetes secrets.

When SKILLFLAW_API_KEY_SOURCE=env, only a single API key can be used for the deployment. All authenticated requests use the same API key, and successful authentication grants superuser privileges. This mode is designed for single-tenant deployments or automated systems, not multi-user environments where different users need different access levels. To rotate your keys, update the environment variable and restart the SkillFlaw server.

To enable environment-based API key validation:

  1. In the SkillFlaw .env file, set the API key source to env:


    _10
    SKILLFLAW_API_KEY_SOURCE=env

  2. In the SkillFlaw .env file, set the API key value:


    _10
    SKILLFLAW_API_KEY=your-secure-api-key

  3. Use the API key in your requests:


    _10
    curl -X POST \
    _10
    "http://SKILLFLAW_SERVER_ADDRESS/api/v1/run/FLOW_ID?stream=false" \
    _10
    -H "Content-Type: application/json" \
    _10
    -H "x-api-key: SKILLFLAW_API_KEY" \
    _10
    -d '{"inputs": {"text":""}, "tweaks": {}}'

    Replace SKILLFLAW_SERVER_ADDRESS, FLOW_ID, and SKILLFLAW_API_KEY with the values from your deployment.

Kubernetes deployment example

To configure an environment-based API key in a Kubernetes Secret, do the following:

  1. Create a Kubernetes Secret with your API key:


    _10
    apiVersion: v1
    _10
    kind: Secret
    _10
    metadata:
    _10
    name: skillflaw-api-key
    _10
    type: Opaque
    _10
    stringData:
    _10
    api-key: "YOUR_API_KEY"

    Replace YOUR_API_KEY with the SKILLFLAW_API_KEY value from the SkillFlaw .env file.

  2. Reference the skillflaw-api-key Secret in your Kubernetes deployment:


    _10
    env:
    _10
    - name: SKILLFLAW_API_KEY_SOURCE
    _10
    value: "env"
    _10
    - name: SKILLFLAW_API_KEY
    _10
    valueFrom:
    _10
    secretKeyRef:
    _10
    name: skillflaw-api-key
    _10
    key: api-key

SKILLFLAW_CORS_*​

Cross-Origin Resource Sharing (CORS) configuration controls how authentication credentials are handled when your SkillFlaw frontend and backend are served from different origins. The following SKILLFLAW_CORS_* environment variables are available:

VariableFormatDefaultDescription
SKILLFLAW_CORS_ALLOW_CREDENTIALSBooleanTrueWhether to allow credentials, such as cookies and authorization headers, in CORS requests.
SKILLFLAW_CORS_ALLOW_HEADERSList[String] or String*The allowed headers for CORS requests. Provide a comma-separated list of headers or use * to allow all headers.
SKILLFLAW_CORS_ALLOW_METHODSList[String] or String*The allowed HTTP methods for CORS requests. Provide a comma-separated list of methods or use * to allow all methods.
SKILLFLAW_CORS_ORIGINSString*The allowed CORS origins. Provide a comma-separated list of origins or use * for all origins.

The default configuration enables CORS credentials and uses wildcards (*) to allow all origins, headers, and methods:


_10
SKILLFLAW_CORS_ORIGINS=*
_10
SKILLFLAW_CORS_ALLOW_CREDENTIALS=True
_10
SKILLFLAW_CORS_ALLOW_HEADERS=*
_10
SKILLFLAW_CORS_ALLOW_METHODS=*

danger

SkillFlaw's default CORS settings can be a security risk in production environments because any website can make requests to your SkillFlaw API, and any website can include credentials in cross-origin requests, including authentication cookies and authorization headers.

In production deployments, specify exact origins in SKILLFLAW_CORS_ORIGINS. You can also specify allowed headers and methods, if needed. For example:


_10
SKILLFLAW_CORS_ORIGINS=["https://yourdomain.com","https://app.yourdomain.com"]
_10
SKILLFLAW_CORS_ALLOW_CREDENTIALS=True
_10
SKILLFLAW_CORS_ALLOW_HEADERS=["Content-Type","Authorization"]
_10
SKILLFLAW_CORS_ALLOW_METHODS=["GET","POST","PUT"]

SSRF protection​

The following environment variables configure Server-Side Request Forgery (SSRF) protection for the API Request component. SSRF protection prevents requests to internal or private network resources, such as private IP ranges, loopback addresses, and cloud metadata endpoints.

VariableFormatDefaultDescription
SKILLFLAW_SSRF_PROTECTION_ENABLEDBooleanFalseEnable SSRF protection for the API Request component. When enabled, the component blocks requests to private IP addresses. When disabled, requests are not blocked.
SKILLFLAW_SSRF_ALLOWED_HOSTSList[String]Not setA comma-separated list of allowed hosts, IP addresses, or CIDR ranges that can bypass SSRF protection checks. For example: 192.168.1.0/24,10.0.0.5,*.internal.company.local.

SKILLFLAW_WEBHOOK_AUTH_ENABLE​

This variable controls whether API key authentication is required for webhook endpoints.

VariableFormatDefaultDescription
SKILLFLAW_WEBHOOK_AUTH_ENABLEBooleanFalseWhen True, webhook endpoints require API key authentication and validate that the authenticated user owns the flow being executed. When False, no SkillFlaw API key is required and all requests to the webhook endpoint are treated as being sent by the flow owner.

By default, webhooks run as the flow owner without authentication with SKILLFLAW_WEBHOOK_AUTH_ENABLE=False.

To require API key authentication for webhooks, in your SkillFlaw .env file, set SKILLFLAW_WEBHOOK_AUTH_ENABLE=True.

When webhook authentication is enabled, you must provide a SkillFlaw API key with each webhook request as an HTTP header or query parameter. For more information, see Require authentication for webhooks.

Configure a secured SkillFlaw server​

This section shows you how to use the authentication environment variables to configure a secured SkillFlaw server. This involves setting superuser credentials, generating a secret encryption key, and configuring user management.

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

SkillFlaw requires explicit authentication flows instead of the removed AUTO_LOGIN mode. Users must sign in to the visual editor with valid credentials, and API requests require authentication with a SkillFlaw API key. Additionally, you must sign in as a superuser to manage users and create a SkillFlaw API key with superuser privileges.

Start the SkillFlaw server​

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


    _10
    SKILLFLAW_SUPERUSER=
    _10
    SKILLFLAW_SUPERUSER_PASSWORD=
    _10
    SKILLFLAW_SECRET_KEY=
    _10
    SKILLFLAW_NEW_USER_IS_ACTIVE=False
    _10
    SKILLFLAW_ENABLE_SUPERUSER_CLI=False

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

  2. Set SKILLFLAW_SUPERUSER and SKILLFLAW_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 SKILLFLAW_SECRET_KEY for encrypting sensitive data.

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

    For instructions on generating and setting a secret key, see SKILLFLAW_SECRET_KEY.

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


    _10
    SKILLFLAW_SUPERUSER=administrator
    _10
    SKILLFLAW_SUPERUSER_PASSWORD=securepassword
    _10
    SKILLFLAW_SECRET_KEY=dBuu...2kM2_fb
    _10
    SKILLFLAW_NEW_USER_IS_ACTIVE=False
    _10
    SKILLFLAW_ENABLE_SUPERUSER_CLI=False

  5. Start SkillFlaw with the configuration from your .env file:


    _10
    uv run skillflaw run --env-file .env

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

Next, you can add users to your SkillFlaw 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 (SKILLFLAW_SUPERUSER and SKILLFLAW_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:

    1. Enter a username and password.
    2. To activate the account immediately, select Active. Inactive users cannot sign in or access flows they created before becoming inactive.
    3. Deselect Superuser if you don't want the user to have full administrative privileges.
    4. Click Save. The new user appears in the Admin Page.

  5. Send the credentials to the user so they can sign in to SkillFlaw. The superuser sets the initial password when creating the account, so users must receive their login credentials from the superuser.

  6. To test the new user's access, sign out of SkillFlaw, 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.

See also​