Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Add an access (security) rule to a file share
Adds a client-access rule to the selected file share (the "Add rule" action in the
the file share detail page Access tab). For NFS shares the rule's source is a client CIDR
(e.g. 10.0.0.0/24) and may set rootSquash; for SMB shares the source is an Active Directory
group or SID (e.g. ACME\Group) and rootSquash is not applicable. permission grants
read/write (rw) or read-only (ro) access. The new rule takes effect on the share's exports
immediately and appears in the share's embedded accessRules list.
Validation: fileShareId must reference a live share (→ 404 NOT_FOUND); source must be a
syntactically valid CIDR for NFS shares or a valid AD group/SID for SMB shares; permission
one of rw|ro; rootSquash only allowed when the share protocol is NFS; a duplicate rule for the
same source → 409 CONFLICT; the per-share rule-count quota is enforced (→ 409 QUOTA_EXCEEDED).
RBAC: owner|admin|contributor.
Async & state: Synchronous; returns 201 with the created AccessRule. The parent share's
rule list change is broadcast as a resource.updated SSE frame with kind "storage.file_share"
patching accessRules and updatedAt; the share itself does not change lifecycle state.
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scopeId or fileShareId;
409 CONFLICT duplicate rule source; 422 invalid source/permission/rootSquash combination; 500
unexpected failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); replaying the same
key returns the
original 201 response (same rule id) instead of appending a duplicate rule.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidapplication/json- body
Request body for storage.file_share.security_rule.create — the "Add rule" form.
source*stringCIDR for NFS shares (e.g. 10.0.0.0/24) or AD group/SID for SMB shares (e.g. ACME\Group).
permission*stringRead/write or read-only access.
"rw""ro"rootSquash?booleanNFS only — map remote root to an unprivileged user. Rejected for SMB shares.
description?stringHuman-readable note for the rule.
length <= 255Access rule created and applied to the share's exports.
application/json- response
Client-access rule of a file share — CIDR-based for NFS, AD group/SID-based for SMB.
id*stringRule identifier within the share.
source*stringCIDR for NFS shares (e.g. 10.0.12.0/24), or AD group/SID for SMB shares (e.g. ACME\Finance).
permission*stringRead/write or read-only access for the source.
"rw""ro"rootSquash?booleanNFS only — map remote root to an unprivileged user. Absent for SMB rules.
description*stringHuman-readable note for the rule.
curl -X POST "https://example.com/scopes/string/storage/file-shares/string/security-rules" \ -H "Content-Type: application/json" \ -d '{ "source": "string", "permission": "rw" }'{ "id": "string", "source": "string", "permission": "rw", "rootSquash": true, "description": "string"}