Organizations & Teams

The K8s Scheduler uses a hierarchical RBAC model with Organizations, Teams, and Members. Organizations contain teams, and teams contain members with specific roles.

Organizations

List User’s Organizations

GET /api/orgs

Returns all organizations the authenticated user is a member of. Authentication: Required (session or API key) Response:

string

Organization UUID

name

string

Organization display name

slug

string

URL-safe organization identifier

plan

string

Billing plan ID (e.g., “free”, “business”, “enterprise”)

aiContext

string

AI template generation context (optional)

createdAt

string

ISO 8601 timestamp

Example:

curl -X GET "https://your-domain.com/api/orgs" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "org_123abc",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "plan": "business",
    "aiContext": "We build developer tools for cloud infrastructure",
    "createdAt": "2024-01-15T10:00:00Z"
  }
]

Get Organization Details

GET /api/orgs/{orgId}

Path Parameters:

orgId

string

required

Organization UUID

Authentication: Required (must be organization member) Response:

string

Organization UUID

name

string

Organization display name

slug

string

URL-safe organization identifier

plan

string

Billing plan ID

aiContext

string

AI template generation context

createdAt

string

ISO 8601 timestamp

Example:

curl -X GET "https://your-domain.com/api/orgs/org_123abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Organization

PUT /api/orgs/{orgId}

Update organization name and AI context. Requires org_owner or org_admin role. Path Parameters:

orgId

string

required

Organization UUID

Request Body:

name

string

New organization name

aiContext

string

AI context for template generation

Example:

curl -X PUT "https://your-domain.com/api/orgs/org_123abc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "aiContext": "Cloud infrastructure tools for developers"
  }'

Teams

List Organization Teams

GET /api/orgs/{orgId}/teams

List all teams in an organization. Regular members only see teams they belong to; owners and admins see all teams. Path Parameters:

orgId

string

required

Organization UUID

Response:

string

Team UUID

orgId

string

Parent organization UUID

name

string

Team display name

slug

string

URL-safe team identifier

createdAt

string

ISO 8601 timestamp

Example:

curl -X GET "https://your-domain.com/api/orgs/org_123abc/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Team

POST /api/orgs/{orgId}/teams

Create a new team. Requires org_owner or org_admin role. The creator is automatically added as team admin. Path Parameters:

orgId

string

required

Organization UUID

Request Body:

name

string

required

Team name

Response: 201 Created with team object Example:

curl -X POST "https://your-domain.com/api/orgs/org_123abc/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering"}'

Get Team Details

GET /api/orgs/{orgId}/teams/{teamId}

Path Parameters:

orgId

string

required

Organization UUID

teamId

string

required

Team UUID

Update Team

PUT /api/orgs/{orgId}/teams/{teamId}

Update team name. Requires org_owner, org_admin, or team_admin role. Request Body:

name

string

required

New team name

Delete Team

DELETE /api/orgs/{orgId}/teams/{teamId}

Delete a team. Requires org_owner or org_admin role. Response: 204 No Content

Organization Members

List Organization Members

GET /api/orgs/{orgId}/members

Response:

string

User ID (also used for member operations)

userId

string

User UUID

string

User email address

role

string

Organization role: org_owner, org_admin, or org_member

joinedAt

string

ISO 8601 timestamp

Example:

curl -X GET "https://your-domain.com/api/orgs/org_123abc/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Organization Member Role

PUT /api/orgs/{orgId}/members/{memberId}

Change a member’s organization role. Requires org_owner role. Request Body:

role

string

required

New role: org_owner, org_admin, or org_member

Response: 204 No Content

Remove Organization Member

DELETE /api/orgs/{orgId}/members/{memberId}

Remove a member from the organization. Requires org_owner role. Response: 204 No Content

Team Members

List Team Members

GET /api/orgs/{orgId}/teams/{teamId}/members

Response:

string

User ID

userId

string

User UUID

string

User email address

role

string

Team role: team_admin, team_developer, or team_viewer

joinedAt

string

ISO 8601 timestamp

Update Team Member Role

PUT /api/orgs/{orgId}/teams/{teamId}/members/{memberId}

Requires org_owner, org_admin, or team_admin role. Request Body:

role

string

required

New role: team_admin, team_developer, or team_viewer

Response: 204 No Content

Remove Team Member

DELETE /api/orgs/{orgId}/teams/{teamId}/members/{memberId}

Response: 204 No Content

Team Invitations

List Team Invites

GET /api/orgs/{orgId}/teams/{teamId}/invites

Response:

string

Invite UUID

string

Invited user’s email

role

string

Role the user will receive: team_admin, team_developer, or team_viewer

expiresAt

string

ISO 8601 timestamp when invite expires

createdAt

string

ISO 8601 timestamp

Create Team Invite

POST /api/orgs/{orgId}/teams/{teamId}/invites

Invite a user to join a team. Requires org_owner, org_admin, or team_admin role. If email sender is configured, an invite email is automatically sent. Request Body:

string

required

Email address to invite

role

string

Team role (default: team_developer)

Response: 201 Created

string

Invite UUID

token

string

Invite token for URL generation

Example:

curl -X POST "https://your-domain.com/api/orgs/org_123abc/teams/team_456def/invites" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "team_developer"
  }'

Delete Team Invite

DELETE /api/orgs/{orgId}/teams/{teamId}/invites/{inviteId}

Cancel a pending invitation. Response: 204 No Content

Accept Invite

POST /api/invites/accept

Accept a team invitation using the invite token. The authenticated user is added to both the organization (as org_member) and the team with the specified role. Request Body:

token

string

required

Invite token from invitation URL or email

Response:

teamId

string

Team UUID the user joined

orgId

string

Organization UUID

role

string

Team role assigned

Example:

curl -X POST "https://your-domain.com/api/invites/accept" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "inv_abc123xyz"}'

Current User Context

Get Current User

GET /api/me

Returns the authenticated user’s profile, organizations, and current team context. Response:

string

User UUID

string

User email

username

string

Unique username

tier

string

Subscription tier

platformRole

string

Platform-level role (e.g., platform_admin)

orgs

array

Array of organizations with user’s role in each

defaultTeam

object

Current active team context

Example:

curl -X GET "https://your-domain.com/api/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Switch Team Context

POST /api/teams/switch

Change the active team context in the session. This affects which team’s resources are shown and which team new deployments are created under. Request Body:

team_id

string

required

Team UUID to switch to (empty string to show all teams)

Response:

success

boolean

Whether the switch succeeded

team_id

string

Active team ID (or null if showing all)

Example:

curl -X POST "https://your-domain.com/api/teams/switch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"team_id": "team_456def"}'

Audit Logs

List Organization Audit Logs

GET /api/orgs/{orgId}/audit

Retrieve audit logs for organization activities. Requires org_owner or org_admin role. Response:

string

Log entry UUID

userId

string

User who performed the action

userEmail

string

User’s email

action

string

Action type (e.g., “create”, “update”, “delete”)

resourceType

string

Type of resource (e.g., “deployment”, “template”, “secret”)

resourceId

string

Resource identifier

resourceName

string

Human-readable resource name

result

string

Result: “success” or “failure”

createdAt

string

ISO 8601 timestamp

Example:

curl -X GET "https://your-domain.com/api/orgs/org_123abc/audit" \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting Started

Core Concepts

Components

Deployment

API Reference

Organizations & Teams

Organizations

List User’s Organizations

Get Organization Details

Update Organization

Teams

List Organization Teams

Create Team

Get Team Details

Update Team

Delete Team

Organization Members

List Organization Members

Update Organization Member Role

Remove Organization Member

Team Members

List Team Members

Update Team Member Role

Remove Team Member

Team Invitations

List Team Invites

Create Team Invite

Delete Team Invite

Accept Invite

Current User Context

Get Current User

Switch Team Context

Audit Logs

List Organization Audit Logs

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Components

Deployment

API Reference

​Organizations

​List User’s Organizations

​Get Organization Details

​Update Organization

​Teams

​List Organization Teams

​Create Team

​Get Team Details

​Update Team

​Delete Team

​Organization Members

​List Organization Members

​Update Organization Member Role

​Remove Organization Member

​Team Members

​List Team Members

​Update Team Member Role

​Remove Team Member

​Team Invitations

​List Team Invites

​Create Team Invite

​Delete Team Invite

​Accept Invite

​Current User Context

​Get Current User

​Switch Team Context

​Audit Logs

​List Organization Audit Logs

Build docs developers (and LLMs) love

Organizations

List User’s Organizations

Get Organization Details

Update Organization

Teams

List Organization Teams

Create Team

Get Team Details

Update Team

Delete Team

Organization Members

List Organization Members

Update Organization Member Role

Remove Organization Member

Team Members

List Team Members

Update Team Member Role

Remove Team Member

Team Invitations

List Team Invites

Create Team Invite

Delete Team Invite

Accept Invite

Current User Context

Get Current User

Switch Team Context

Audit Logs

List Organization Audit Logs