User Management

Manage users within workspaces in multi-tenant deployments. Users can have ADMIN or USER roles, each with different permissions.

Admin APIs require root_api_key to be configured in the server. ROOT users can manage all accounts, while ADMIN users can only manage their own workspace.

Roles and Permissions

Role	Permissions
ROOT	System administrator with full access to all workspaces
ADMIN	Workspace administrator, manages users within their account
USER	Regular user with access to their own data

Operation	ROOT	ADMIN	USER
Register/remove users	All accounts	Own account only	❌
Regenerate user key	All accounts	Own account only	❌
List users	All accounts	Own account only	❌
Change user role	✅	❌	❌

Register User

Register a new user in a workspace.

Authentication: ROOT or ADMIN (own account only)

Path Parameters

account_id · string · required

Workspace ID where the user will be registered

Request Body

user_id · string · required

Unique user identifier within the workspace

role · string · default: "user"

User role: admin or user

Response

status · string

Response status (ok or error)

result · object

Registration result

Show Result Object

account_id · string

Workspace ID

user_id · string

Registered user ID

user_key · string

Generated API key for the 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/acme/users \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <admin-or-root-key>" \
  -d '{
    "user_id": "bob",
    "role": "user"
  }'

Response

{
  "status": "ok",
  "result": {
    "account_id": "acme",
    "user_id": "bob",
    "user_key": "d91f5b2a8e3c7f1a..."
  },
  "time": 0.12
}

List Users

List all users in a workspace.

Authentication: ROOT or ADMIN (own account only)

Path Parameters

account_id · string · required

Workspace ID to list users from

Response

status · string

Response status (ok or error)

result · array

Array of users in the workspace

Show User Object

user_id · string

User identifier

role · string

User role (admin or user)

time · number

Request processing time in seconds

Example

cURL

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

Response

{
  "status": "ok",
  "result": [
    {
      "user_id": "alice",
      "role": "admin"
    },
    {
      "user_id": "bob",
      "role": "user"
    }
  ],
  "time": 0.05
}

Remove User

Remove a user from a workspace. The user’s API key is immediately invalidated.

Authentication: ROOT or ADMIN (own account only)

Path Parameters

account_id · string · required

Workspace ID

user_id · string · required

User ID to remove

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/users/bob \
  -H "X-API-Key: <admin-or-root-key>"

Response

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

Set User Role

Change a user’s role. ROOT only.

Authentication: ROOT only

Path Parameters

account_id · string · required

Workspace ID

user_id · string · required

User ID

Request Body

role · string · required

New role: admin or user

Response

status · string

Response status (ok or error)

result · object

Role change result

Show Result Object

account_id · string

Workspace ID

user_id · string

User ID

role · string

New role

time · number

Request processing time in seconds

Example

cURL

curl -X PUT http://localhost:1933/api/v1/admin/accounts/acme/users/bob/role \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <root-key>" \
  -d '{"role": "admin"}'

Response

{
  "status": "ok",
  "result": {
    "account_id": "acme",
    "user_id": "bob",
    "role": "admin"
  },
  "time": 0.06
}

Regenerate API Key

Regenerate a user’s API key. The old key is immediately invalidated.

Authentication: ROOT or ADMIN (own account only)

The old API key becomes invalid immediately. Ensure the new key is distributed to the user before they need to make API calls.

Path Parameters

account_id · string · required

Workspace ID

user_id · string · required

User ID

Response

status · string

Response status (ok or error)

result · object

New key

Show Result Object

user_key · string

New API key (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/acme/users/bob/key \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <admin-or-root-key>"

Response

{
  "status": "ok",
  "result": {
    "user_key": "e82d4e0f9c1b5a3d..."
  },
  "time": 0.07
}

Complete Workflow Example

# Step 1: ROOT creates workspace with alice as first admin
openviking admin create-account acme --admin alice
# Returns alice's user_key

# Step 2: alice (admin) registers regular user bob
openviking admin register-user acme bob --role user
# Returns bob's user_key

# Step 3: List all users in the account
openviking admin list-users acme

# Step 4: ROOT promotes bob to admin
openviking admin set-role acme bob admin

# Step 5: bob lost their key, regenerate (old key immediately invalidated)
openviking admin regenerate-key acme bob

# Step 6: Remove user
openviking admin remove-user acme bob

Related Endpoints

• API Key Management - Workspace management
• System Status - Check current user