Orgs & Projects

Multi-tenant hierarchy for the Pug platform. All analytics data is scoped to a project.

Services: OrgsService, ProjectsService
Auth: JWT + x-project-id (for project-scoped operations)

Hierarchy


Organization
├── Members (roles: admin, member, viewer)
├── Billing
├── Email provider config
└── Projects
    ├── API keys (SDK + shared)
    ├── Events
    ├── Profiles
    └── Dashboards

Organizations are the billing and member boundary. Projects are the data boundary — events, profiles, and dashboards never cross project lines.

OrgsService

Manage organizations and membership.

Method	Description
`Create`	Create a new organization
`Get`	Get org details
`List`	List orgs for the authenticated user
`Update`	Update org name and settings
`InviteMember`	Send email invitation
`ListMembers`	List org members and roles
`RemoveMember`	Remove a member

Invite member


{
  "email": "teammate@example.com",
  "role": "ROLE_MEMBER"
}

See Members for role permissions.

ProjectsService

Manage projects within an org.

Method	Description
`Create`	Create a new project
`Get`	Get project details
`List`	List projects in the org
`Update`	Update project name, timezone
`CreateApiKey`	Generate a new API key
`ListApiKeys`	List active API keys
`RevokeApiKey`	Revoke an API key

Create project


{
  "name": "Production",
  "timezone": "America/New_York"
}

Set timezone at creation — it affects all Insights bucket boundaries. Changing it later shifts historical chart boundaries.

Create API key


{
  "type": "API_KEY_TYPE_SDK",
  "name": "Web app production"
}
 
// Response
{
  "apiKey": {
    "id": "key_abc123",
    "key": "pk_sdk_...",
    "type": "API_KEY_TYPE_SDK",
    "createdAt": "2026-06-01T10:00:00Z"
  }
}

Key type	Use in
`API_KEY_TYPE_SDK`	Browser/mobile SDK `init()`
`API_KEY_TYPE_SHARED`	Server-side scripts, cron jobs

The raw key value is only returned once at creation. Store it immediately — it cannot be retrieved again.

Rotate an API key

CreateApiKey — generate new key
Update SDK init or server env vars
Deploy
RevokeApiKey — revoke old key

Scoping rules

Resource	Scoped to
Events, profiles, dashboards	Project
API keys	Project
Members, billing, email provider	Organization

A JWT for org A cannot access org B’s projects. An API key for project X cannot write to project Y.

Request headers

All dashboard API requests:


Authorization: Bearer <jwt>
x-project-id: <project-id>
Content-Type: application/json
Connect-Protocol-Version: 1

SDK requests:


Authorization: Bearer <sdk-api-key>
x-project-id: <project-id>

See Authentication for client setup examples.

TypeScript client


import { ProjectsService } from './gen/projects/v1/projects_connect'
 
const client = createClient(ProjectsService, jwtTransport)
 
const { project } = await client.create({
  name: 'Staging',
  timezone: 'UTC'
})
 
const { apiKey } = await client.createApiKey({
  projectId: project.id,
  type: 'API_KEY_TYPE_SDK',
  name: 'Staging web app'
})
 
console.log('Store this key now:', apiKey.key)