Skip to main content
Key-based authentication lets you authenticate fal API requests using a secret key generated from the dashboard. This is the recommended authentication method for production applications, CI/CD pipelines, and any environment where you need programmatic access. Each key carries a permission set that controls the operations the key can do. You can create and manage keys from the fal dashboard at any time.

​
Overview

There are two main reasons to use key-based authentication:
  1. When calling ready-to-use models
  2. In headless remote environments or CI/CD (where GitHub authentication is not available)

​
Generating the keys

Navigate to our dashboard keys page and generate a key from the UI fal.ai/dashboard/keys

​
Permissions

Permissions control what a key can do. When you create a key, you select a preset or a custom permission list. A permission name has parts that colons separate, for example models:requests:submit, serverless:apps:write, or models:list.

​
Presets

A preset is a permission list that fal curates for a common case. If you only consume ready-to-use models, use the API preset.
If you are not sure which preset to select, start with API. You can create a second key with more permissions when you need one.

​
Custom policies

If no preset matches your case, select the exact permissions the key needs. A custom policy is useful when you must grant one narrow capability, such as a key that only submits requests to your own app.

​
Allowed models

You can limit a key to a list of models in the Allowed models tab when you create the key. You cannot change the limit after creation. A key with this limit can only call the models on the list.
If you add a model limit to a preset, fal stores the key as a custom policy. The key then keeps the preset permissions from the moment of creation, and it no longer follows the live preset.

​
How a key resolves its permissions

A key resolves its permissions under one of two contracts:
  • A preset key stores only the preset name. fal curates the presets and can refine a definition, and the key follows the live definition. A change to the preset applies to the key at its next request.
  • A custom policy key stores the full permission list. The list is a snapshot from the moment of creation, and fal does not redefine it.
If the permissions of a key must stay the same for the life of the key, use a custom policy.

​
Expiration

When you create a key, you can set it to expire after a period from 1 hour to 1 year, or never. The keys page shows an Expiring soon badge before a key expires, and an Expired badge after. An expired key cannot authenticate requests. To replace it, create a new key.

​
Legacy scopes

Keys created before presets carry the legacy ADMIN or API scope, and they continue to work. An ADMIN key has full access to the account, and the closest preset is FULL. An API key can call models, and the closest preset is API. To move a legacy key to the preset model, create a new key with a preset and revoke the old key.