Workspace Management

Manage workspaces (accounts) in multi-tenant OpenViking deployments. Workspaces provide isolated environments for teams with separate data, users, and API keys.

Admin APIs require root_api_key to be configured in the server. Only ROOT users can create and delete workspaces.

Workspace Architecture

Each workspace has:

• Isolated AGFS storage (viking://user/, viking://agent/, etc.)
• Separate VectorDB namespace
• Independent user management
• At least one ADMIN user

Create Workspace

Create a new workspace with its first admin user. This initializes all required directories and storage.

Authentication: ROOT only

Request Body

account_id · string · required

Unique workspace identifier

admin_user_id · string · required

User ID for the first admin of this workspace

Response

status · string

Response status (ok or error)

result · object

Creation result

Show Result Object

account_id · string

Created workspace ID

admin_user_id · string

Admin user ID

user_key · string

Generated API key for the admin user (save this - it cannot be retrieved later)

time · number

Request processing time in seconds

Example

cURL

curl -X POST http://localhost:1933/api/v1/admin/accounts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <root-key>" \
  -d '{
    "account_id": "acme",
    "admin_user_id": "alice"
  }'

Response

{
  "status": "ok",
  "result": {
    "account_id": "acme",
    "admin_user_id": "alice",
    "user_key": "7f3a9c1e5d2b8a4f..."
  },
  "time": 0.25
}

List Workspaces

List all workspaces with user counts and creation timestamps.

Authentication: ROOT only

Response

status · string

Response status (ok or error)

result · array

Array of workspaces

Show Workspace Object

account_id · string

Workspace identifier

created_at · string

ISO 8601 timestamp of creation

user_count · number

Number of users in the workspace

time · number

Request processing time in seconds

Example

cURL

curl -X GET http://localhost:1933/api/v1/admin/accounts \
  -H "X-API-Key: <root-key>"

Response

{
  "status": "ok",
  "result": [
    {
      "account_id": "default",
      "created_at": "2026-02-12T10:00:00Z",
      "user_count": 1
    },
    {
      "account_id": "acme",
      "created_at": "2026-02-13T08:00:00Z",
      "user_count": 3
    },
    {
      "account_id": "corp",
      "created_at": "2026-03-01T14:30:00Z",
      "user_count": 7
    }
  ],
  "time": 0.08
}

Delete Workspace

Delete a workspace and all associated data including users, API keys, AGFS storage, and VectorDB records.

Authentication: ROOT only

This operation is irreversible. All workspace data will be permanently deleted:

• All users and their API keys
• All AGFS data (viking://user/, viking://agent/, viking://session/, viking://resources/)
• All VectorDB embeddings and metadata

Path Parameters

account_id · string · required

Workspace ID to delete

Response

status · string

Response status (ok or error)

result · object

Deletion result

Show Result Object

deleted · boolean

Always true on success

time · number

Request processing time in seconds

Example

cURL

curl -X DELETE http://localhost:1933/api/v1/admin/accounts/acme \
  -H "X-API-Key: <root-key>"

Response

{
  "status": "ok",
  "result": {
    "deleted": true
  },
  "time": 0.45
}

Cascade Deletion Details

When a workspace is deleted, the following cleanup occurs:

1. AGFS Data Cleanup

All directories for the account are removed:

viking://user/          # User personal data
viking://agent/         # Skills and agent data
viking://session/       # Session data
viking://resources/     # Uploaded resources

2. VectorDB Cleanup

All vectors and metadata tagged with the account ID are deleted from:

• Context collection
• Any custom collections

3. User and Key Cleanup

All users in the workspace and their API keys are removed from the key manager.

Complete Workflow Example

# Step 1: Create workspace
curl -X POST http://localhost:1933/api/v1/admin/accounts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <root-key>" \
  -d '{
    "account_id": "acme",
    "admin_user_id": "alice"
  }'
# Save alice's user_key from response

# Step 2: Alice adds users (using her admin key)
curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <alice-key>" \
  -d '{
    "user_id": "bob",
    "role": "user"
  }'

curl -X POST http://localhost:1933/api/v1/admin/accounts/acme/users \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <alice-key>" \
  -d '{
    "user_id": "carol",
    "role": "user"
  }'

# Step 3: List all workspaces (ROOT)
curl -X GET http://localhost:1933/api/v1/admin/accounts \
  -H "X-API-Key: <root-key>"

# Step 4: Check users in acme workspace
curl -X GET http://localhost:1933/api/v1/admin/accounts/acme/users \
  -H "X-API-Key: <alice-key>"

# Step 5: Delete workspace (removes all data)
curl -X DELETE http://localhost:1933/api/v1/admin/accounts/acme \
  -H "X-API-Key: <root-key>"

Configuration

To enable admin APIs, configure the root API key in your server:

# Set root API key (environment variable)
export OPENVIKING_ROOT_API_KEY="your-secure-root-key"

# Or in config file
root_api_key: "your-secure-root-key"

# Start server
openviking serve --config config.yaml

Generate a secure root key:

openssl rand -hex 32

Multi-Tenant Best Practices

Use Strong Root Keys

The root API key has full system access. Generate cryptographically secure keys and store them securely (e.g., in a secrets manager).

# Generate secure 256-bit key
openssl rand -hex 32

Minimize Root Key Usage

• Create workspaces and initial admins with ROOT
• Let ADMIN users manage their own workspace users
• Only use ROOT for workspace deletion and role changes

Name Workspaces Consistently

Use lowercase identifiers with hyphens:

• acme-corp ✅
• team-alpha ✅
• AcmeCorp ❌
• team_alpha ❌

Plan for Workspace Lifecycle

• Create workspaces for teams/projects
• Archive data before deletion
• Remove unused workspaces periodically
• Monitor workspace resource usage

Related Endpoints

• User Management - Manage users within workspaces
• System Status - Check system health