Create API Key

Creates a new API key with the specified alias.

Keys are created with granular permissions. Pass preset for a named preset or permissions to list them explicitly; omit both to get the API preset.

Important Security Notice: The key_secret is only returned once at creation time. Store it securely immediately as it cannot be retrieved again. If lost, you must delete the key and create a new one.

Key Features:

Create API keys programmatically without UI access
Assign meaningful aliases for key identification
Scope a key with a named preset or an explicit list of permissions
Optionally set an expiry with expires_at
Keys are immediately active upon creation

Common Use Cases:

Programmatic key provisioning for CI/CD pipelines
Self-serve key generation for team members
Automated key rotation workflows
Integration with secret management systems

Required permissions: auth:keys:write. Key presets that include them: FULL. See key permissions.

POST

keys

Create API Key

curl --request POST \
  --url https://api.fal.ai/v1/keys \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "alias": "Production Key"
}
'

import requests

url = "https://api.fal.ai/v1/keys"

payload = { "alias": "Production Key" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({alias: 'Production Key'})
};

fetch('https://api.fal.ai/v1/keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "key_id": "abc123def456",
  "key_secret": "sk_live_abc123def456xyz789",
  "key": "abc123def456:sk_live_abc123def456xyz789"
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Key on the FULL preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_API_KEY

Body

application/json

alias

string

required

Required friendly name for the API key

Required string length: 1 - 255

Example:

"Production Key"

description

string

Optional description of what the key is for

Maximum string length: 1000

Example:

"CI deploy key for the main environment"

preset

enum<string>

Named permission preset to apply. Defaults to "API" when neither preset nor permissions is given. Mutually exclusive with permissions.

Available options:

FULL,

AGENT,

API,

DEPLOY,

READONLY,

BILLING,

COMPUTE,

SERVERLESS

Example:

"API"

permissions

string[]

Explicit list of permissions to grant instead of a preset. Mutually exclusive with preset.

Minimum array length: 1

Example:

[
  "models:requests:read",
  "models:requests:write"
]

expires_at

string<date-time>

ISO8601 timestamp after which the key stops working

Example:

"2025-07-15T12:00:00Z"

Response

API key created successfully. Store the key_secret securely - it will not be shown again.

Response containing the newly created API key credentials. The key_secret is only returned once.

key_id

string

required

Unique identifier for the newly created API key

Example:

"abc123def456"

key_secret

string

required

Secret portion of the API key. IMPORTANT: This is only returned once at creation time and cannot be retrieved again.

Example:

"sk_live_abc123..."

key

string

required

Full API key in the format 'key_id:key_secret'. Use this value directly for API authorization. IMPORTANT: This is only returned once at creation time and cannot be retrieved again.

Example:

"abc123def456:sk_live_abc123..."

⌘I

Create API Key

curl --request POST \
  --url https://api.fal.ai/v1/keys \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "alias": "Production Key"
}
'

import requests

url = "https://api.fal.ai/v1/keys"

payload = { "alias": "Production Key" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({alias: 'Production Key'})
};

fetch('https://api.fal.ai/v1/keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "key_id": "abc123def456",
  "key_secret": "sk_live_abc123def456xyz789",
  "key": "abc123def456:sk_live_abc123def456xyz789"
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}