Authentication

Generating API Keys

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

Permissions

Platform APIs require different key permissions. Learn more about key-based authentication and permissions.

API preset

Most Platform APIs accept a key with the API preset. This preset covers model discovery, model analytics, and the requests you submit.

Other presets

Some Platform APIs read sensitive data and need more permissions. Billing endpoints need the BILLING preset, compute endpoints need the COMPUTE preset, and a key with the FULL preset reaches every endpoint.

Match the preset to the surface you call. If you are not sure, start with a key on the API preset. You can create a key with more permissions later.

API keys should be kept secure and never exposed in client-side code or public repositories.

Authentication Format

Include your API key in the Authorization header with the Key prefix:

Authorization: Key YOUR_API_KEY

The header is the same for every preset. Only the permissions of the key change.

Usage Examples

cURL

Using a key on the API preset for model listing:

curl -X GET "https://api.fal.ai/v1/models?limit=10" \
  -H "Authorization: Key YOUR_API_KEY"

Using a key on the BILLING preset for usage data:

curl -X GET "https://api.fal.ai/v1/models/usage" \
  -H "Authorization: Key YOUR_BILLING_API_KEY"

Python

Using a key on the API preset:

import requests

headers = {
    "Authorization": "Key YOUR_API_KEY"
}

response = requests.get(
    "https://api.fal.ai/v1/models",
    headers=headers,
    params={"limit": 10}
)

print(response.json())

JavaScript

Using a key on the API preset:

const response = await fetch('https://api.fal.ai/v1/models?limit=10', {
  headers: {
    'Authorization': 'Key YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

Best Practices

Store API keys in environment variables
Use the preset with the fewest permissions for your use case
Rotate keys regularly
Keep FULL preset keys secure and never expose them client-side

Troubleshooting

401 Unauthorized

Verify your API key is correct
Ensure the Authorization header includes the Key prefix
Check that your API key hasn’t been revoked

403 Forbidden

The key does not carry the permission the endpoint requires. Create a key on the preset that covers the surface you call, such as BILLING for billing endpoints or COMPUTE for compute endpoints.

​Generating API Keys

​Permissions

API preset

Other presets

​Authentication Format

​Usage Examples

​cURL

​Python

​JavaScript

​Best Practices

​Troubleshooting

​401 Unauthorized

​403 Forbidden

Generating API Keys

Permissions

Authentication Format

Usage Examples

cURL

Python

JavaScript

Best Practices

Troubleshooting

401 Unauthorized

403 Forbidden