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

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

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

artifacts:read,artifacts:create,artifacts:update

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

​

Use a key

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

Environment variable

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

​

Run non-interactively

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

export AGENT_ARTIFACTS_NO_INPUT=1
export AGENT_ARTIFACTS_TOKEN="aa_k_..."

artifacts artifact list --format json

​

Manage keys

List

artifacts keys list

REST equivalents:

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

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.