Set file ACL

Replaces the Access Control List of a fal CDN file.

The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users may be specified by nickname or user ID. Setting default to allow with no rules makes the file public; forbid or hide restricts it to the rules you provide.

Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent.

Authentication: Required. The API key must have the assets:write permission.

PUT

/

storage

/

files

/

acl

Set file ACL

curl --request PUT \
  --url https://api.fal.ai/v1/storage/files/acl \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "default": "forbid"
}
'

{
  "default": "forbid",
  "rules": [
    {
      "user": "my-teammate",
      "decision": "allow"
    }
  ]
}

Authorizations

Authorization

string

header

required

API key must be prefixed with "Key ", e.g. Authorization: Key YOUR_API_KEY

Query Parameters

url

string<uri>

required

Full URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b//). Must not contain query parameters.

Example:

"https://v3.fal.media/files/b/0a1b2c3d/output.png"

Body

application/json

Access Control List for a fal CDN file

default

enum<string>

required

Fallback decision when no user-specific rule matches

Available options:

allow,

forbid,

hide

Example:

"allow"

rules

object[]

User-specific overrides to the default decision

Show child attributes

Response

ACL applied to the file

Access Control List currently applied to the file

default

enum<string>

required

Fallback decision when no user-specific rule matches

Available options:

allow,

forbid,

hide

Example:

"allow"

rules

object[]

required

User-specific overrides to the default decision. Users are returned as nicknames where possible.

Show child attributes

Sign file URL Creates a signed URL that grants temporary access to a fal CDN file, regardless of its ACL. Useful for sharing access-restricted files. The signature is valid for `expiration_seconds` (up to 7 days). **Authentication:** Required. The API key must have the `assets:read` permission.

⌘I

Set file ACL

curl --request PUT \
  --url https://api.fal.ai/v1/storage/files/acl \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "default": "forbid"
}
'

{
  "default": "forbid",
  "rules": [
    {
      "user": "my-teammate",
      "decision": "allow"
    }
  ]
}