Skip to content

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.

ref
required
integer format: int64

The asset type’s ref.

object
principal_type
required
string
Allowed values: user role team
principal_id
required

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.

string
<= 64 characters /^([0-9]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/
permission
required
string
Allowed values: read write admin
expires_at

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.

string format: date-time
nullable

The grant was saved, or an existing grant for the same principal and level was updated.

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed