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.

Required permissions: assets:write. Key presets that include them: API, SERVERLESS, FULL. See key permissions.

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

import requests

url = "https://api.fal.ai/v1/storage/files/acl"

payload = { "default": "forbid" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

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

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

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

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

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

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

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "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 API preset, or any key whose permissions include the ones this API lists. APIs with no required permission accept any key. Prefix it 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

⌘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"
}
'

import requests

url = "https://api.fal.ai/v1/storage/files/acl"

payload = { "default": "forbid" }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

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

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

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

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

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

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

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

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

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