Key-Based Authentication

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 https://www.fal.ai/dashboard/keys (opens in a new tab)

Alternatively, run the following command to generate a key pair with the scope of your choice. The ADMIN scope gives you access to use the SDK, whereas API gives you access to call ready-to-use models (opens in a new tab). You will find more details on scopes at the bottom of this page.

fal key generate --scope ADMIN

If successful, the following message should be printed out in your terminal:

Generated key id and key secret.
This is the only time the secret will be visible.
You will need to generate a new key pair if you lose access to this secret.
 
FAL_KEY_ID='your-key-id'
FAL_KEY_SECRET='your-key-secret'

You should store the values of FAL_KEY_ID and FAL_KEY_SECRET in your environment now.

Using the keys

In order to use key-based credentials, you need to set two environment variables FAL_KEY_ID and FAL_KEY_SECRET:

export FAL_KEY_ID="your-key-id"
export FAL_KEY_SECRET="your-key-secret"

fal will automatically detect the above variables. Please note that key-based auth will take precedence if both key-based and GitHub auth are set in an environment.

Scopes

Scopes provide a way to control the permissions and access level of a given key. By assigning scopes to keys, you can limit the operations that each key can perform. Currently there are only two scopes, ADMIN and API. If you are just consuming ready-to-use models, we recommend that you use the API scope.

API scope

• Grants access to ready-to-use models.

ADMIN scope

• Grants full access to the SDK.
• Grants full access to CLI operations.
• Grants access to ready-to-use models.