Add a grant to an asset type
POST /asset_types/{ref}/acls
Adds a grant to an asset type. Once a type has a grant, the type
list shows it only to holders of system.admin granted globally and
to people covered by a grant that hasn’t expired.
A body or ref that can’t be read gets a plain-text 400 before
anything else is checked. Then you need to be signed in with
system.asset_types.admin or system.admin granted globally;
others get 403, whether or not the type exists. The grant’s fields
are checked next, and only then does a ref with no type answer
404.
principal_type can be user, role or team. For user,
principal_id is the account’s numeric ref; zero, a negative or a
non-numeric value is refused with 400. For role and team it’s
the UUID, and a value that isn’t one is refused with 400; a UUID
with capitals, without hyphens, in braces or with a urn:uuid:
prefix is accepted but stored as sent, so it matches no one. Nothing
is looked up, so an account, role or team that doesn’t exist is
accepted. permission must be read, write or admin, and
anything else gets 400. principal_type and permission accept
capitals, but not surrounding spaces.
The level makes no difference: read, write and admin each let
the people covered see the type in the type list, and nothing more.
None of them lets anyone manage the type’s grants, and none is
checked when uploading or reading assets. Without expires_at the
grant doesn’t expire. A time that has already passed is accepted;
the grant then gives no access but still keeps the type restricted.
Each principal and level is one grant. Sending the same principal
and level again replaces its expiry (leaving expires_at out makes
it permanent) and records you and the current time as its latest
grant; a different level is a separate grant. When two requests
change the same grant at once, the one saved last stands.
From the first grant on, holders of system.admin granted globally
still see the type, and everyone else needs a grant that hasn’t
expired and covers them, holders of system.asset_types.admin alone
included, though they can still manage its grants. Nobody is
notified, and no activity or audit entry is recorded. Server errors
get a plain-text 500.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset type’s ref.
Request Body required
Section titled “Request Body required ”object
Who the grant is for, by reference rather than name: for user, the
account’s numeric ref in plain digits; for role or team, its
UUID in lowercase.
The value is stored exactly as sent and compared as written, so a ref with leading zeros or a plus sign is accepted but matches no one. Each route’s description says which principal types it accepts.
When the grant should stop giving access. Leave it out or send null for a grant that doesn’t expire. A time that has already passed is accepted, but the grant gives no access.
Responses
Section titled “ Responses ”The grant was saved, or an existing grant for the same principal and level was updated.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completed