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

string

Organization display name

string

URL-safe organization identifier

string

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

string

AI template generation context (optional)

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:

string

required

Organization UUID

Authentication: Required (must be organization member) Response:

string

Organization UUID

string

Organization display name

string

URL-safe organization identifier

string

Billing plan ID

string

AI template generation context

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:

string

required

Organization UUID

Request Body:

string

New organization name

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:

string

required

Organization UUID

Response:

string

Team UUID

string

Parent organization UUID

string

Team display name

string

URL-safe team identifier

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:

string

required

Organization UUID

Request Body:

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:

string

required

Organization UUID

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:

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)

string

User UUID

string

User email address

string

Organization role: org_owner, org_admin, or org_member

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:

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

string

User UUID

string

User email address

string

Team role: team_admin, team_developer, or team_viewer

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:

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

string

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

string

ISO 8601 timestamp when invite expires

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

string

Team role (default: team_developer)

Response: 201 Created

string

Invite UUID

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": "newdev@example.com",
    "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:

string

required

Invite token from invitation URL or email

Response:

string

Team UUID the user joined

string

Organization UUID

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

string

Unique username

string

Subscription tier

string

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

array

Array of organizations with user’s role in each

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:

string

required

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

Response:

boolean

Whether the switch succeeded

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

string

User who performed the action

string

User’s email

string

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

string

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

string

Resource identifier

string

Human-readable resource name

string

Result: “success” or “failure”

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

​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

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