List API Keys

Returns a list of all API keys belonging to the authenticated user’s workspace.

Key Features:

View all API keys with their aliases and creation dates
See how each key is permissioned via mode, preset and permissions
Optionally expand to include creator information
Paginated results for workspaces with many keys

Key Modes:

preset: created from a named permission preset, reported in preset
custom: created with an explicit list of permissions
legacy: predates granular permissions and carries a coarse scope

Expansion Options:

expand=creator_info: Include creator_nickname and creator_email for each key

Common Use Cases:

Audit existing API keys
Find keys by alias
Monitor key creation activity
Build key management interfaces

Required permissions: auth:keys:read. Key presets that include them: BILLING, FULL. See key permissions.

GET

keys

List API Keys

curl --request GET \
  --url https://api.fal.ai/v1/keys \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

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

{
  "keys": [
    {
      "key_id": "abc123def456",
      "alias": "Production Key",
      "created_at": "2025-01-15T12:00:00Z",
      "mode": "preset",
      "preset": "API",
      "permissions": [
        "account:settings:read",
        "assets:read",
        "assets:write",
        "auth:tokens:create",
        "models:list",
        "models:metrics:read",
        "models:requests:cancel",
        "models:requests:read",
        "models:requests:share",
        "models:requests:submit",
        "serverless:metrics:read",
        "serverless:requests:read",
        "workflows:read",
        "workflows:submit"
      ],
      "expires_at": null
    },
    {
      "key_id": "xyz789ghi012",
      "alias": "Inference Key",
      "created_at": "2025-01-10T09:30:00Z",
      "mode": "custom",
      "permissions": [
        "models:list",
        "models:requests:read",
        "models:requests:submit"
      ],
      "expires_at": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

{
  "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 BILLING preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_API_KEY

Query Parameters

limit

integer

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Required range: x >= 1

Example:

50

cursor

string

Pagination cursor from previous response. Encodes the page number.

Example:

"Mg=="

expand

Fields to expand in the response. Available: creator_info (includes creator_nickname and creator_email)

Example:

["creator_info"]

Response

Successfully retrieved API keys

Response containing a list of API keys with pagination support

next_cursor

string | null

required

Cursor for the next page of results, null if no more pages

has_more

boolean

required

Boolean indicating if more results are available (convenience field derived from next_cursor)

keys

object[]

required

Array of API keys belonging to the authenticated user

Hide child attributes

keys.key_id

string

required

Unique identifier for the API key

Example:

"abc123def456"

keys.alias

string

required

User-provided friendly name for the key

Example:

"Production Key"

keys.created_at

string

required

ISO8601 timestamp when the key was created

Example:

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

keys.mode

enum<string>

required

How the key's permissions are expressed: a named preset, a custom permission list, or a legacy scope.

Available options:

legacy,

preset,

custom

Example:

"preset"

keys.expires_at

string | null

required

ISO8601 timestamp when the key expires, or null if it doesn't

Example:

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

keys.scope

enum<string>

deprecated

Coarse scope of a legacy API key. Deprecated: superseded by mode, preset and permissions, and omitted for keys that carry granular permissions.

Available options:

API,

ADMIN

Example:

"API"

keys.description

string

User-provided description of what the key is for

Example:

"CI deploy key for the main environment"

keys.preset

enum<string>

Preset the key was created from, present when mode is preset

Available options:

FULL,

AGENT,

API,

DEPLOY,

READONLY,

BILLING,

COMPUTE,

SERVERLESS

Example:

"API"

keys.permissions

string[]

Resolved permissions, present for preset and custom keys

Minimum array length: 1

Example:

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

keys.creator_nickname

string

Nickname of the user who created this key (when expanded)

Example:

"developer"

keys.creator_email

string

Email of the user who created this key (when expanded)

Example:

"developer@example.com"

⌘I

List API Keys

curl --request GET \
  --url https://api.fal.ai/v1/keys \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

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

{
  "keys": [
    {
      "key_id": "abc123def456",
      "alias": "Production Key",
      "created_at": "2025-01-15T12:00:00Z",
      "mode": "preset",
      "preset": "API",
      "permissions": [
        "account:settings:read",
        "assets:read",
        "assets:write",
        "auth:tokens:create",
        "models:list",
        "models:metrics:read",
        "models:requests:cancel",
        "models:requests:read",
        "models:requests:share",
        "models:requests:submit",
        "serverless:metrics:read",
        "serverless:requests:read",
        "workflows:read",
        "workflows:submit"
      ],
      "expires_at": null
    },
    {
      "key_id": "xyz789ghi012",
      "alias": "Inference Key",
      "created_at": "2025-01-10T09:30:00Z",
      "mode": "custom",
      "permissions": [
        "models:list",
        "models:requests:read",
        "models:requests:submit"
      ],
      "expires_at": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

{
  "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"
  }
}