Skip to main content

Write Restriction (writeAccess)

A type can restrict who may write its runtime entities. With a writeAccess block, only the listed principal kinds and trusted service channels may create, update, replace or delete entities of the type, or change associations that have such an entity at either end. Everyone else is refused with message 144, and nothing is written.

The block requires ckLanguage: 2.

types:
- typeId: KnowledgePage
derivedFromCkTypeId: ${System}/Entity
writeAccess:
principals: [ Interactive ]
channels: [ System.Ai/KnowledgeTools ]
KeyValuesWho may write
principalsInteractive, Client (exact spelling)Interactive: a user who signed in. Client: a service that authenticated with client credentials.
channels<namespace>/<name>, for example System.Ai/KnowledgeToolsA service that writes through its own guarded code path and marks its session with this channel.

A write is allowed when the caller's principal kind is listed or its session carries a listed channel.

Rules​

  • Derived types inherit the block. If a derived type declares its own block as well, every block along the inheritance chain must allow the write. A derived type can narrow the restriction, but never widen it.
  • Associations count as writes. Adding or removing an association whose source or target is a restricted entity needs the right to write that entity.
  • System writes are never restricted. Pipelines, blueprint seed data, blueprint updates and CK model migrations write as the system and keep working.
  • Types without a block of their own or of a base type are unchanged. For them it does not matter what kind of caller writes.
  • No client ids in the model. Client ids differ between tenants and clusters. A channel is not a client id: the service sets it in its own code on the session it opens. It never comes from a token, a header or anything else the caller sends.

Where it is enforced​

The engine checks the restriction on every write that a user or a service makes for a caller:

  • GraphQL create, update and delete mutations and REST writes,
  • runtime imports started by a user or client (ImportRt): the whole file is refused before anything is written, with one error that lists every refused entity.

The service that opens the session tells the engine whether the caller is an interactive user or a client. If it does not know, the caller is refused for restricted types (it is only admitted through a listed channel).

Service support

From release 3.5.71 the asset repository reports the kind for GraphQL and REST writes, and for runtime imports started by a user or client it passes the kind to the import job, which the bot services apply from release 3.5.71 as well (both services must run 3.5.71; an older bot service imports as Unknown): a token with a user subject (sub) is Interactive; a client-credentials token, and a token in which a service acts for a user (delegation or impersonation), is Client; anything else is Unknown. Mixed versions: with an older asset repository every GraphQL, REST and import caller is Unknown; with an older bot service only runtime imports run as Unknown, GraphQL and REST writes are classified. Unknown is admitted only through a listed channel. Imports queued before the upgrade also keep running as Unknown. So restrict a type that users or clients must keep writing only after the asset repository and the bot services of your environment run 3.5.71 and the import jobs queued before the upgrade have finished or been queued again (see Status).

Compiler checks​

The compiler refuses an invalid block with message 143:

  • a block that lists neither principals nor channels,
  • an empty principals or channels list,
  • a principal kind other than Interactive or Client,
  • a channel that does not have the form <namespace>/<name> (letters, digits and underscores; each part starts with a letter; the namespace may contain dots),
  • the same entry twice.

An unknown key inside the block is a schema error (message 27). In a model without ckLanguage: 2 the block is message 90.

Compatibility​

  • A model that uses writeAccess requires engine 3.5.71 or later (minEngineVersion). Older release engines refuse the model with message 126 instead of ignoring the restriction. Main-line builds below version 1.0 skip this check (see Engine version contract); import such a model there only when every service runs an engine that knows writeAccess.
  • Adding, removing or changing a block is a Minor change that must be acknowledged with a security reason (compatibility.acknowledge), see the versioning rules.
  • Models without the block compile exactly as before.