Access control

ACL determines who can read, edit, or manage shared sources within one account. Use it for project collaboration, selected readers, and group-based maintenance.

This page creates a shared directory managed by Alice and readable by Bob, then checks reading, denied writes, and revocation. Account administrators retain implicit management access to shared sources.

Prerequisites

Complete Authentication and prepare acme-admin, acme-alice, and acme-bob connections. Alice and Bob are ordinary users so that the checks exercise their grants.

ACL applies to viking://resources/.... Personal memories, private sources, and Peer spaces retain their User boundary. See Knowledge sharing to share selected content from those spaces.

Enable ACL

Acme's administrator sets the service address and enters team-admin's Admin key with hidden input:

export OV_URL="http://127.0.0.1:1933"
read -r -s ADMIN_KEY
export ADMIN_KEY

Enable ACL checks for the account:

curl -sS -X PATCH "$OV_URL/api/v1/admin/accounts/acme/configuration" \
  -H "X-API-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings":{"acl":{"enabled":true}}}'

Check that result.settings.acl.enabled is true. This switch defaults to off; shared sources are not ACL-filtered while it is off. Writing grants does not enable the switch automatically.

Create a restricted directory

The shared root grants manage to everyone in the account, and descendants inherit parent permissions. Use restricted to cut off inheritance and assign direct grants when limiting access to selected members.

The administrator creates a new example directory:

ov config switch acme-admin
ov mkdir viking://resources/team-knowledge \
  --acl '{"acl_mode":"restricted","entries":[{"principal":"user:alice","level":"manage"},{"principal":"user:bob","level":"read"}]}'

If it already exists, inspect its grants with ov acl get. Choose a fresh name for this walkthrough to preserve existing grants.

Level	Allowed operations
read	Read, list, and retrieve
write	Includes read, plus writing, creating, deleting, or moving files
manage	Includes write, plus managing ACL and deleting or moving directories

Write a source

Alice publishes a note. Writing triggers semantic and vector processing, requiring available models and incurring model calls:

ov config switch acme-alice
ov write viking://resources/team-knowledge/access-check.md \
  --mode create --content "Team agreement: summarize project feedback every Friday." --wait

The new file inherits the directory grants. Inspect the directory ACL and original content:

ov acl get viking://resources/team-knowledge
ov read viking://resources/team-knowledge/access-check.md

If waiting times out, check the returned task ID and continue after processing completes.

Verify as Bob

Bob uses his own connection to read and retrieve:

ov config switch acme-bob
ov read viking://resources/team-knowledge/access-check.md
ov find "When is project feedback summarized?" --uri viking://resources/team-knowledge

Reading should succeed and retrieval should include the note. Try creating a file:

ov write viking://resources/team-knowledge/bob-check.md \
  --mode create --content "Bob's write check."

Bob has only read, so the write should be denied. If it succeeds, check whether the active identity is an administrator, whether account ACL is enabled, and whether other effective grants permit writing.

Change grants

Alice has manage and can grant Bob editing access:

ov config switch acme-alice
ov acl grant viking://resources/team-knowledge --principal user:bob --level write

Bob can rerun the preceding write command; it should now succeed. To return to reading only, set the level back to read. To end access, revoke the direct grant:

ov acl grant viking://resources/team-knowledge --principal user:bob --level read
ov acl revoke viking://resources/team-knowledge --principal user:bob

Alice runs these two commands. Switch to Bob afterward; reading access-check.md should be denied. Permission indexing can have a short delay. Check every two seconds for up to 30 seconds initially; if access continues, inspect effective permissions and other grant sources.

revoke removes the direct entry on this node. Access from a parent or group remains effective. Revocation also does not remove already downloaded copies. To continue with the next sharing walkthrough, Alice restores Bob's read grant.

Grant to a group

For larger teams, an administrator can create an account-local group and manage its members, then grant access to group:<group_id>. Membership changes apply to subsequent requests. This is useful for project subteams; see Admin API for group and membership operations.

Next steps

Continue to Knowledge sharing to publish accumulated project knowledge into this controlled directory. See ACL concepts for inheritance and directory-move behavior.