Workspaces

Workspaces are the top-level organizational unit in Orphnet Logging. Every project, API key, and log belongs to a workspace. Workspaces enable team collaboration with role-based access control.

Personal vs Team Workspaces

When you register, a personal workspace is created automatically. It is marked with is_personal: true and cannot be deleted.

You can create additional team workspaces for collaboration:

curl -X POST https://api.logvista.orph.dev/workspaces \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Team",
    "slug": "my-team"
  }'

Response (201):

{
  "success": true,
  "data": {
    "id": "ws_...",
    "name": "My Team",
    "slug": "my-team",
    "owner_id": "usr_..."
  }
}

Slug requirements

Slugs must be 3-48 characters. If a collision occurs during personal workspace creation, a 4-character hex suffix is appended automatically.

Roles and Permissions

Each workspace member has one of three roles:

Role	Permissions
Owner	Full control: delete workspace, transfer ownership, manage all members, all admin/member permissions
Admin	Invite members, remove members, create projects, manage API keys
Member	Read access, create logs, query logs

Role hierarchy uses numeric values: owner (3) > admin (2) > member (1).

Authentication-Based Access

• JWT path (user sessions): Authorization is checked via workspace role. Scope checks are skipped.
• API key path (programmatic access): Authorization is checked via key scopes. Role checks are skipped.

Listing Workspaces

List all workspaces you belong to:

curl https://api.logvista.orph.dev/workspaces \
  -H "Authorization: Bearer eyJ..."

Inviting Members

Admins and owners can invite new members:

curl -X POST https://api.logvista.orph.dev/workspaces/members/invite \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Workspace-Id: ws_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "colleague@example.com",
    "role": "member"
  }'

An invitation email is sent with a token. The invitee accepts by:

curl -X POST https://api.logvista.orph.dev/workspaces/invitations/{token}/accept \
  -H "Authorization: Bearer eyJ..."

Auto-join on registration

If someone registers with an email that has a pending invitation, they are automatically added to the workspace. This is best-effort -- failures do not block registration.

Managing Members

Update a Member's Role

Only the workspace owner can change roles:

curl -X PATCH https://api.logvista.orph.dev/workspaces/members/{userId}/role \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Workspace-Id: ws_..." \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

Remove a Member

Admins and owners can remove members:

curl -X DELETE https://api.logvista.orph.dev/workspaces/members/{userId} \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Workspace-Id: ws_..."

Transferring Ownership

Only the current owner can transfer ownership:

curl -X POST https://api.logvista.orph.dev/workspaces/transfer \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Workspace-Id: ws_..." \
  -H "Content-Type: application/json" \
  -d '{ "newOwnerId": "usr_..." }'

The previous owner becomes an admin.

Deleting a Workspace

Only the owner can delete a workspace. Personal workspaces cannot be deleted.

curl -X DELETE https://api.logvista.orph.dev/workspaces \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Workspace-Id: ws_..."

Cascade behavior

Deleting a workspace nullifies workspace_id on associated projects and API keys rather than deleting them outright.

Workspace Context Header

Most workspace-scoped API calls require the X-Workspace-Id header. The workspaceMiddleware validates that:

1. The header is present and the workspace exists
2. The authenticated user is a member of that workspace
3. The user's role meets the minimum required for the operation

Next Steps

• API Keys -- Create workspace and project-scoped API keys
• Authentication -- Set up user authentication
• API Reference: Workspaces -- Full endpoint documentation