API Tokens & Authentication

Token Types

Account tokens (art_)

• Created in the web UI under Settings > API Tokens.
• Act as your user identity -- same access as logging in via the web UI.
• Access is based on your membership roles across orgs and repos.
• Best for: local development, personal scripts.

Organization tokens (org_)

• Created in the web UI under Org Settings > Organization Tokens (requires org admin role).
• Grant access to all repositories in the organization based on the token's scopes.
• Do not require user membership checks -- the token itself is the authorization.
• Can create repositories and manage repo tokens programmatically (with admin scope).
• Cannot create other org tokens (prevents privilege escalation).
• Best for: CI/CD pipelines, automated integrations like Eventer.

Repository tokens (rep_)

• Created in the web UI under Repo Settings > Repository Tokens, or programmatically via an org_ admin token.
• Grant access to exactly one repository.
• Do not require user membership checks.
• Best for: customer-facing tokens, read-only distribution, narrowly scoped access.

Scopes

All token types use the same scope system. Scopes are hierarchical:

When creating a token, select one or more scopes. The token's effective permission is the highest scope selected.

Authentication Methods

Three ways to authenticate with any Artifacts API endpoint:

Bearer token (most common)

Authorization: Bearer art_your_token
Authorization: Bearer org_your_token
Authorization: Bearer rep_your_token

Used by: npm CLI (via _authToken), Swift PM, curl, and any HTTP client.

Basic auth (Maven/Gradle)

Authorization: Basic base64("token:art_your_token")

The username can be any string (conventionally token). The password is your API token. All three prefixes work.

Used by: Maven (settings.xml), Gradle (credentials { }).

Firebase ID token (web UI only)

Authorization: Bearer eyJhbG...

Used internally by the web UI. Not relevant for CLI or API usage.

Token Management API

Account tokens

# List your account tokens
curl https://artifacts.premex.se/api/auth/token \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

# Create an account token
curl -X POST https://artifacts.premex.se/api/auth/token \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-cli-token", "scopes": ["read", "write"], "expiresInDays": 90}'

# Delete an account token
curl -X DELETE "https://artifacts.premex.se/api/auth/token?tokenId=TOKEN_ID" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

Note: Account token management requires Firebase authentication (web session). API tokens cannot manage other account tokens.

Organization tokens

# List org tokens (Firebase auth or org_ admin token)
curl https://artifacts.premex.se/api/orgs/ORGSLUG/tokens \
  -H "Authorization: Bearer $TOKEN"

# Create an org token (Firebase auth only -- requires org admin role)
curl -X POST https://artifacts.premex.se/api/orgs/ORGSLUG/tokens \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "scopes": ["read", "write", "admin"], "expiresInDays": 365}'

# Delete an org token (Firebase auth or org_ admin token)
curl -X DELETE "https://artifacts.premex.se/api/orgs/ORGSLUG/tokens?tokenId=TOKEN_ID" \
  -H "Authorization: Bearer $TOKEN"

Repository tokens

# List repo tokens (Firebase auth or org_ admin token)
curl https://artifacts.premex.se/api/repos/REPO_ID/tokens \
  -H "Authorization: Bearer $TOKEN"

# Create a repo token (Firebase auth or org_ admin token)
curl -X POST https://artifacts.premex.se/api/repos/REPO_ID/tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer-readonly", "scopes": ["read"]}'

# Delete a repo token (Firebase auth or org_ admin token)
curl -X DELETE "https://artifacts.premex.se/api/repos/REPO_ID/tokens?tokenId=TOKEN_ID" \
  -H "Authorization: Bearer $TOKEN"

Create token response

All create endpoints return the same shape:

{
  "token": {
    "id": "abc123",
    "tokenType": "repo",
    "name": "customer-readonly",
    "tokenPrefix": "rep_a1b2c3d4",
    "scopes": ["read"],
    "expiresAt": "2027-02-26T00:00:00.000Z",
    "createdAt": "2026-02-26T12:00:00.000Z"
  },
  "rawToken": "rep_a1b2c3d4e5f6..."
}

Important: rawToken is only returned at creation time. The full token is never stored and cannot be retrieved later. Store it securely.

Create token fields

Programmatic Repo & Token Management

Organization tokens with admin scope can manage repos and repo tokens via the API, enabling fully automated workflows:

ORG_TOKEN="org_..."  # Created once in the web UI

# Create a new repository
curl -X POST https://artifacts.premex.se/api/repos \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-acme",
    "orgId": "ORGSLUG",
    "packageTypes": ["npm"],
    "visibility": "private"
  }'

# Create a read-only token for that repository
curl -X POST https://artifacts.premex.se/api/repos/REPO_ID/tokens \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-readonly", "scopes": ["read"]}'

This is the pattern used by CI/CD systems that need to provision per-customer repositories with scoped tokens.

Which Token Should I Use?

• Just developing locally? Use an account token (art_). Easiest to set up, uses your existing permissions.
• CI/CD pipeline for one org? Use an org token (org_) with write scope. Publishes to any repo in the org.
• Distributing to external consumers? Use a repo token (rep_) with read scope. Limits access to exactly one repo.
• Automated infra that creates repos? Use an org token (org_) with admin scope. Can create repos and issue repo tokens programmatically.

Security Best Practices

• Never commit tokens to source control. Use environment variables or secret managers.
• Use the narrowest scope possible. Read-only tokens for consumers, write for CI, admin only when managing infrastructure.
• Set expiration dates for tokens used in CI/CD. Rotate them periodically.
• Use repo tokens for external parties. If a token leaks, only one repository is exposed.
• Org tokens cannot create other org tokens. This is intentional -- only web UI admins can mint new org tokens, preventing programmatic privilege escalation.