Using Fixtures to Seed Uptrace Data

Data fixtures let you programmatically create and manage users, organizations, and projects in Uptrace using YAML or JSON configuration files. Fixtures are idempotent: applying the same file twice produces the same state, making them safe to use in CI/CD pipelines and multi-environment setups.

The key system

Each resource has a key field — a stable, user-defined identifier. Uptrace uses it to:

Track resources across multiple fixture runs
Update existing resources instead of creating duplicates
Establish references between resource types (e.g. a project references an org by key)

Keys are case-sensitive and must be unique within each resource type.

Supported resources

Users — individual user accounts
User tokens — API tokens for programmatic access
Organizations — top-level containers
Organization users — user membership and roles within an org
Projects — monitoring projects within an org
Project tokens — API tokens scoped to a project
Project users — user permissions within a project

Configuration

YAML configuration (self-hosted only)

Define fixtures directly in uptrace.yml:

yaml

seed_data:
  users:
    - key: admin_user
      name: System Administrator
      email: admin@company.com
      password: change_me_immediately

  orgs:
    - key: main_org
      name: Acme Corporation

  org_users:
    - key: admin_membership
      org: main_org
      user: admin_user
      role: owner

  projects:
    - key: web_app_project
      name: Web Application
      org: main_org
    - key: api_project
      name: REST API
      org: main_org

JSON API (cloud and self-hosted)

Both cloud and self-hosted instances support the JSON API for dynamic fixture management.

Authentication

Include your user token in API requests:

text

Authorization: Bearer <your_user_token>

Generate a token at User profile → Auth tokens.

Syncing fixtures

bash

curl https://api.uptrace.dev/api/v1/fixtures \
  --request PUT \
  --header "Authorization: Bearer <user_token>" \
  --header "Content-Type: application/json" \
  --data @fixtures.json

If a resource with the same key already exists, Uptrace updates it. If a resource key is removed from the fixture, it is deleted.

JSON schema

json

{
  "users": [
    {
      "key": "user1",
      "name": "Display Name",
      "email": "user@example.com",
      "password": "secure_password"
    }
  ],
  "userTokens": [
    {
      "key": "token1",
      "userKey": "user1",
      "token": "api_token",
      "name": "CI/CD Token"
    }
  ],
  "orgs": [
    {
      "key": "org1",
      "name": "Organization",
      "description": "Optional description"
    }
  ],
  "orgUsers": [
    {
      "key": "org_user1",
      "orgKey": "org1",
      "userKey": "user1",
      "role": "owner"
    }
  ],
  "projects": [
    {
      "key": "project1",
      "name": "Project Name",
      "orgKey": "org1"
    }
  ],
  "projectTokens": [
    {
      "key": "proj_token1",
      "projectKey": "project1",
      "token": "project_secret",
      "name": "Production Token"
    }
  ],
  "projectUsers": [
    {
      "key": "proj_user1",
      "projectKey": "project1",
      "orgUserKey": "org_user1",
      "permLevel": "admin"
    }
  ]
}

Roles and permissions

Organization roles: owner, admin, member, viewer, collaborator, billing_manager

Project permission levels: admin, maintain, view, none

Working with existing resources

When you need to reference resources created through the Uptrace UI in your fixtures, use the binding API to assign keys to them:

bash

curl https://api.uptrace.dev/api/v1/fixtures/bindings \
  --request PUT \
  --header "Authorization: Bearer <user_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "orgs": [
      {"id": 123, "key": "legacy_org"}
    ],
    "projects": [
      {"id": 456, "key": "existing_project"}
    ]
  }'

Supported binding models: orgs, orgUsers, projects, projectTokens.

Example: multi-environment setup

json

{
  "orgs": [
    {"key": "company_prod", "name": "Production"},
    {"key": "company_staging", "name": "Staging"}
  ],
  "projects": [
    {"key": "app_prod",     "name": "Main Application", "orgKey": "company_prod"},
    {"key": "app_staging",  "name": "Main Application", "orgKey": "company_staging"}
  ]
}

Security guidelines

Never commit passwords to version control — use placeholder values and rotate immediately
Use environment variables for sensitive values in automation scripts
Create service accounts with minimal required permissions for CI/CD
Rotate tokens regularly, especially in production environments

Observability as Code — Terraform-based management of monitors, channels, and projects
SSO — manage user access through an identity provider instead of manual fixtures