Access and permissions

Principals, roles, scopes, public access, share links, and how policy is enforced.

Artifacts has one authorization layer. Whether a request comes from the web app, REST API, CLI, or MCP server, it’s evaluated as a principal against the same policy — so access behaves identically everywhere.

Principals

A principal is whoever is making a request.

Principal	Used by
user	Signed-in humans using Better Auth sessions
api_key	Scoped bearer tokens for CLI, CI, and automation
agent	Agent-owned credentials
oauth_client	OAuth clients such as MCP clients
service	Internal service actors, including share-link resolution

Principals can also carry scopes and artifact role grants.

Artifact roles

Roles are ranked from most to least privileged:

owner > admin > editor > viewer

Each role unlocks a set of actions:

Action	Meaning
artifact.view	Read metadata and source content
artifact.create	Create artifacts in a namespace
artifact.update	Append a new version
artifact.restore	Restore an older version as the new head
artifact.diff	Compare two versions
artifact.delete	Soft-delete an artifact
artifact.manage_access	Read or update access settings
artifact.create_share_link	Create share links
artifact.revoke_share_link	Revoke share links
project.view	View projects in a namespace

Public access

Each artifact has two public switches:

{
  "publicView": true,
  "publicEdit": false
}

• publicView grants viewer access to unauthenticated callers.
• publicEdit grants editor access to public callers, when the plan allows public edit links.

Private artifacts require an owning user, a workspace member, an email allowlist match, an API key or OAuth principal with permission, or a share link.

Email allowlists

Grant view access to specific people by email:

{
  "publicView": false,
  "publicEdit": false,
  "viewerEmails": ["[e-mail]"]
}

Email viewers must sign in with a verified email that matches the allowlist. This requires a plan that includes private artifacts and email allowlists.

Share links

Share links grant viewer or editor access to a single artifact, and can optionally expire:

artifacts share create \
  --artifact-id ARTIFACT_ID \
  --role viewer \
  --expires-at 2026-06-30T12:00:00.000Z

Share links require Pro or Team entitlements.

API key scopes

API keys are bearer credentials with explicit scopes — grant only what each job needs.

Scope	Purpose
artifacts:read	Read artifacts, versions, diffs, and project lists
artifacts:create	Create artifacts and projects
artifacts:update	Append versions and restore
artifacts:delete	Soft-delete artifacts
artifacts:share	Create and revoke share links
artifacts:access:read	Read access settings
artifacts:access:write	Update access settings
agents:manage	Manage API keys and agent credentials

artifacts keys create --name ci --scopes artifacts:read,artifacts:create,artifacts:update

Treat API keys as secrets. The raw key is only shown at creation time — store it in a secret manager and pass it through environment variables or stdin.

What each plan unlocks

Some access features are plan-gated:

Feature	Free	Pro	Team
Private artifacts	No	Yes	Yes
Email allowlist	No	Yes	Yes
Share links	No	Yes	Yes
Public edit links	No	Yes	Yes
Audit retention	7 days	90 days	365 days
Version history	30 days	365 days	365 days