Admin Module

The Admin module provides internal endpoints for Cosmo's operations team. All endpoints are protected by AdminSecretGuard, which requires the CLERK_SECRET_KEY as a bearer token. Source: packages/server/src/modules/admin/.

REST Endpoints

All endpoints are prefixed with /api/v1/admin and require AdminSecretGuard.

Org Management

Method	Path	Description
POST	`/admin/orgs`	Create an org + owner user directly
DELETE	`/admin/orgs/:orgId`	Delete an org from Clerk + DB

Enterprise Management

Method	Path	Description
GET	`/admin/enterprise`	List all ENTERPRISE plan orgs
GET	`/admin/enterprise/:orgId`	Get enterprise org with seat audit log
POST	`/admin/enterprise`	Provision an org onto the ENTERPRISE plan
PATCH	`/admin/enterprise/:orgId/seats`	Update purchased seat count (with audit)

Release Management

Method	Path	Description
POST	`/admin/releases`	Publish a new desktop release
GET	`/admin/releases`	List all releases
PATCH	`/admin/releases/:id`	Update release (rollout %, mandatory, etc.)

Admin Service (`admin.service.ts`)

`createOrg({ orgName, ownerEmail, ownerName })`

Provisions a complete org directly without going through Clerk sign-up:

Creates the Clerk organisation.
Creates the Clerk user with the provided email.
Adds the user as OWNER of the Clerk org.
Syncs both records to the local DB.
Mints and returns a Cosmo JWT for the new owner.

Used for enterprise org provisioning and testing.

`deleteOrg(orgId)`

Looks up the org's Clerk ID.
Deletes the Clerk organisation (which cascades membership deletion).
Deletes the local Organization record (cascades to all related DB records).

`listEnterpriseOrgs()`

Returns all Organization records with plan: ENTERPRISE, including their subscription and recent audit log entries.

`getEnterpriseOrg(orgId)`

Returns a single enterprise org with its full EnterpriseSeatAudit history, subscription details, and member count.

`provisionEnterprise({ orgId, purchasedSeats, changedBy, notes })`

Moves an org to the ENTERPRISE plan:

Sets plan: ENTERPRISE on the Organization record.
Creates or updates the Subscription with status: ACTIVE.
Sets purchasedSeats on the subscription.
Creates the first EnterpriseSeatAudit entry.

`updateSeats({ orgId, purchasedSeats, changedBy, notes })`

Updates seat count for an enterprise org:

Records the previous seat count.
Updates purchasedSeats on the subscription.
Creates an EnterpriseSeatAudit entry with oldSeats, newSeats, changedBy, and notes.

Enterprise Seat Audit

Every seat count change is logged in EnterpriseSeatAudit:

Field	Description
`oldSeats`	Seat count before this change
`newSeats`	Seat count after this change
`changedBy`	Admin identifier (email or service name)
`notes`	Reason for the change
`createdAt`	Timestamp of the change

This audit trail is used for billing reconciliation and contract management.

AdminSecretGuard

packages/server/src/common/guards/admin-secret.guard.ts extracts the bearer token from Authorization: Bearer <token> and compares it against process.env.CLERK_SECRET_KEY using crypto.timingSafeEqual — preventing timing-attack extraction of the secret.

Returns 401 Unauthorized if the token is missing or incorrect.

On this page