> ## Documentation Index
> Fetch the complete documentation index at: https://artifacts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={"theme":"github-dark"}
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:

```json theme={"theme":"github-dark"}
{
  "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:

```json theme={"theme":"github-dark"}
{
  "publicView": false,
  "publicEdit": false,
  "viewerEmails": ["teammate@example.com"]
}
```

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:

```bash theme={"theme":"github-dark"}
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              |

```bash theme={"theme":"github-dark"}
artifacts keys create --name ci --scopes artifacts:read,artifacts:create,artifacts:update
```

<Warning>
  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.
</Warning>

## 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 |