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 |
Artifact roles
Roles are ranked from most to least privileged:
owner > admin > editor > viewer
| 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": ["teammate@example.com"]
}
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
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 |
