Sub-Organizations

Koyeb sub-organizations let you manage fleets of Koyeb services and other resources programmatically, at scale, with:

• Simplified governance: Create, configure, and manage multiple sub-organizations from a central Koyeb user account
• Strong isolation: Each sub-organization is fully independent with its own Koyeb resources and complete network isolation
• Granular usage tracking: Query detailed usage metrics per sub-organization via the Koyeb API
• Seamless product integration: Map your customers to sub-organizations and manage their resources programmatically
• Custom subdomain configuration: Expose applications through your own domains (e.g., *.myservice.tld), instead of the default koyeb.app subdomain

In short, using sub-organization you can provision and control independent environments while maintaining strict separation of customer data and resources.

Managing sub-organizations

To start using sub-organizations, your account must be on the Enterprise Plan. Once enabled, you first need to create new user account token.

A user account token allows you to:

• Perform authenticated API calls to the Koyeb API
• Create and manage sub-organizations
• Switch to a sub-organization context to create and manage Koyeb resources

As a real-world example, let's take a concrete scenario to illustrate how to use sub-organizations. Below, we will walk you through the steps to:

1. Create a user account token
2. Create a new sub-organization
3. Switch to the sub-organization to create and deploy a Koyeb resources

Create a user account token

Sub-organizations are created using Koyeb API. These API calls are authenticated with a user account token.

To create a user account token, follow these steps:

1. Navigate to the Koyeb control panel (opens in a new tab).
2. Click on the user's name near the bottom of the sidebar > User settings.
3. In Personal account settings click the Personal access tokens tab.
4. Click Create access token. Give your token a meaningful name and description, then click Create.
5. Copy the access token and store it in a secure place. You won't be able to access it again.

Create a sub-organization

To create a new sub-organization, perform a POST request to the /v1/organizations API endpoint.

This POST request must include:

• A value for name that uniquely identifies the sub-organization, included in the body of the request, i.e. {"name": "my-sub-org"}
• The user account token you created in the previous step, provided in the Authorization header

To execute this request using curl, use the following command:

curl -s https://api.koyeb.com/v1/organizations \
    -d '{"name": "my-sub-org"}' \
    -H "Authorization: Bearer YOUR_USER_ACCOUNT_TOKEN"

This request creates the sub-organization and return a response similar to the following:

{ 
  "organization": {
    "id":"cc660219-a822-4660-a0ca-2a0d16ca1422",
    "name": "my-sub-org",
    "plan": "partner_csp_unit",
    "status": "ACTIVE",
    "status_message": "VALID",
    ...
  }
}

With the new sub-organization created, the next step is to switch to its context to create and deploy a Koyeb service. To do this, you’ll need the organization ID.

Switch to the sub-organization to create and deploy a Koyeb resources

With the new sub-organization created, we can now switch to its context to create and deploy Koyeb services and other resources.

To switch to a sub-organization, send a POST request to the /v1/organizations/:id/switch API endpoint.

This POST request must include:

• The sub-organization ID, provided in the path of the request, e.g. /v1/organizations/cc660219-a822-4660-a0ca-2a0d16ca1422/switch
• The user account token you created in the previous step, provided in the Authorization header

To execute this request using curl, run the following command:

curl -s https://api.koyeb.com/v1/organizations/cc660219-a822-4660-a0ca-2a0d16ca1422/switch \
    -X POST \
    -H "Authorization: Bearer YOUR_USER_ACCOUNT_TOKEN"

This call returns a JSON object similar to the following, which includes a token.id field. This is a sub-organization token that you must use (instead of your original user account token) for all subsequent API calls within this sub-organization:

{
    "token": {
        "id": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "user_id": "00000000-4567-43c7-1234-1a9f29a5d3b3",
        "organization_id": "cc660219-a822-4660-a0ca-2a0d16ca1422",
        "expires_at": "2025-09-11T14:01:24.758700305Z"
    }
}

Using this token, you can create a new Koyeb app and any other organization related resources like domains, services, secrets, volumes, etc. in the sub-organization.

For instance, to create a new Koyeb app, perform the following curl command on the /v1/apps API endpoint:

curl -s https://api.koyeb.com/v1/apps \
    -d '{"name": "my-app"}' \
    -H "Authorization: Bearer YOUR_SUB_ORG_TOKEN"

This request will create a new Koyeb app and return a response similar to the following:

{
    "app": {
        "id": "12345678-1234-5678-9abc-123456789abc",
        "name": "my-app",
        "organization_id": "cc660219-a822-4660-a0ca-2a0d16ca1422"
    }
}

Other important considerations

• User account tokens are required to create and manage sub-organizations via the API
• You can list and manage all sub-organizations using the /v1/organizations API endpoint with your user account token
• All sub-organizations and their resources are also visible in the Koyeb control panel (opens in a new tab)
• For questions about custom subdomain configuration, pricing, or additional support, please contact us (opens in a new tab)