> ## Documentation Index
> Fetch the complete documentation index at: https://fal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.
    



## OpenAPI

````yaml /api-reference/platform-apis/openapi/v1.json put /storage/files/acl
openapi: 3.1.0
info:
  title: Platform APIs
  version: v1
  description: fal REST API for programmatic access to platform resources.
servers:
  - url: https://api.fal.ai/v1
    description: Production server
security: []
paths:
  /storage/files/acl:
    put:
      tags:
        - Storage
      summary: Set file ACL
      description: >-

        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.
            
      operationId: setStorageFileAcl
      parameters:
        - schema:
            type: string
            format: uri
            description: >-
              Full URL of the fal CDN file, as returned by the upload APIs
              (https://v3.fal.media/files/b/<id>/<filename>). Must not contain
              query parameters.
            example: https://v3.fal.media/files/b/0a1b2c3d/output.png
          required: true
          description: >-
            Full URL of the fal CDN file, as returned by the upload APIs
            (https://v3.fal.media/files/b/<id>/<filename>). Must not contain
            query parameters.
          name: url
          in: query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                default:
                  type: string
                  enum:
                    - allow
                    - forbid
                    - hide
                  description: Fallback decision when no user-specific rule matches
                  example: allow
                rules:
                  type: array
                  items:
                    type: object
                    properties:
                      user:
                        type: string
                        minLength: 1
                        description: User nickname or user ID the rule applies to
                        example: some-user
                      decision:
                        type: string
                        enum:
                          - allow
                          - forbid
                          - hide
                        description: Access decision applied to this user
                        example: allow
                    required:
                      - user
                      - decision
                    additionalProperties: false
                    description: A per-user access control rule
                  default: []
                  description: User-specific overrides to the default decision
              required:
                - default
              additionalProperties: false
              description: Access Control List for a fal CDN file
            example:
              default: forbid
              rules:
                - user: my-teammate
                  decision: allow
      responses:
        '200':
          description: ACL applied to the file
          content:
            application/json:
              schema:
                type: object
                properties:
                  default:
                    type: string
                    enum:
                      - allow
                      - forbid
                      - hide
                    description: Fallback decision when no user-specific rule matches
                    example: allow
                  rules:
                    type: array
                    items:
                      type: object
                      properties:
                        user:
                          type: string
                          minLength: 1
                          description: User nickname or user ID the rule applies to
                          example: some-user
                        decision:
                          type: string
                          enum:
                            - allow
                            - forbid
                            - hide
                          description: Access decision applied to this user
                          example: allow
                      required:
                        - user
                        - decision
                      additionalProperties: false
                      description: A per-user access control rule
                    description: >-
                      User-specific overrides to the default decision. Users are
                      returned as nicknames where possible.
                required:
                  - default
                  - rules
                description: Access Control List currently applied to the file
              example:
                default: forbid
                rules:
                  - user: my-teammate
                    decision: allow
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: validation_error
                  message: Invalid request parameters
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: authorization_error
                  message: Authentication required
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: authorization_error
                  message: Access denied
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: not_found
                  message: Resource not found
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: rate_limited
                  message: Rate limit exceeded
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                          - validation_error
                          - not_found
                          - rate_limited
                          - server_error
                          - not_implemented
                        description: The category of error that occurred
                      message:
                        type: string
                        description: Human-readable error message
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant documentation
                      request_id:
                        type: string
                        description: Unique request identifier for debugging
                    required:
                      - type
                      - message
                    description: Error details
                required:
                  - error
                description: Standard error response format
              example:
                error:
                  type: server_error
                  message: An unexpected error occurred
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key must be prefixed with "Key ", e.g. Authorization: Key
        YOUR_API_KEY

````