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

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));

200

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

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

200

application/json

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