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

# API keys and automation

> Create scoped bearer credentials for CI, scripts, services, and non-interactive agents.

Use API keys when automation can't complete a browser login. They authenticate with bearer auth, skip CSRF checks, and carry explicit scopes — so each job gets exactly the access it needs and nothing more.

## Create a key

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

If you omit `--scopes`, the CLI defaults to:

```text theme={"theme":"github-dark"}
artifacts:read,artifacts:create,artifacts:update
```

<Warning>
  The raw secret is shown once, at creation. Store it in your secret manager immediately — never commit it.
</Warning>

## Use a key

Provide the token through an environment variable, or pipe it in over stdin to keep it off the process list.

<CodeGroup>
  ```bash Environment variable theme={"theme":"github-dark"}
  export AGENT_ARTIFACTS_BASE_URL="https://api.example.com"
  export AGENT_ARTIFACTS_TOKEN="aa_k_..."

  # whoami resolves the key's owner — including your username — so you don't need
  # to know it out of band. --owner is optional on push; when omitted the API
  # infers it from the key.
  artifacts whoami --format json
  artifacts push --project-slug default --file ./report.md --no-input
  ```

  ```bash stdin theme={"theme":"github-dark"}
  printf '%s\n' "$AGENT_ARTIFACTS_TOKEN" | artifacts --token-stdin whoami
  ```

  ```bash REST theme={"theme":"github-dark"}
  curl "$API_URL/api/profile/me" \
    -H "authorization: Bearer $AGENT_ARTIFACTS_TOKEN"
  ```
</CodeGroup>

## Run non-interactively

Set `AGENT_ARTIFACTS_NO_INPUT=1` (or pass `--no-input`) so jobs fail fast instead of trying to open a browser:

```bash theme={"theme":"github-dark"}
export AGENT_ARTIFACTS_NO_INPUT=1
export AGENT_ARTIFACTS_TOKEN="aa_k_..."

artifacts artifact list --format json
```

## Manage keys

<CodeGroup>
  ```bash List theme={"theme":"github-dark"}
  artifacts keys list
  ```

  ```bash Revoke theme={"theme":"github-dark"}
  artifacts keys revoke --api-key-id KEY_ID
  ```
</CodeGroup>

REST equivalents:

```text theme={"theme":"github-dark"}
GET    /api/api-keys
DELETE /api/api-keys/:apiKeyId
```

## Available scopes

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

## Example: publish a report from CI

```bash theme={"theme":"github-dark"}
set -euo pipefail

export AGENT_ARTIFACTS_BASE_URL="https://api.example.com"
export AGENT_ARTIFACTS_NO_INPUT=1

bun run build:report
# --owner is inferred from the key; pass it only to publish into another account.
artifacts push \
  --token "$AGENT_ARTIFACTS_TOKEN" \
  --project-slug ci \
  --file ./out/report.html \
  --title "CI report for $GITHUB_SHA" \
  --private \
  --format json
```

## Stay safe

* Give each automation its own key.
* Use the smallest scope set that completes the job.
* Prefer environment variables or stdin over flags on shared hosts.
* Revoke keys the moment a job or agent is retired.
* Use `--dry-run` to preview mutating CLI calls while building a pipeline.