Organizations, Units, and Projects

The Aiven Platform uses a three-tier hierarchy to help you efficiently and securely organize your services and manage access. This structure provides flexibility while maintaining centralized control over billing, authentication, and security policies.

Hierarchy overview

The Aiven Platform organizes resources into three levels:

Organization

Top-level entity containing all projects and services

Organizational Unit

Optional grouping of projects within an organization

Project

Collection of services sharing network and access settings

Example structure

Acme Corporation (Organization)
├── Engineering Unit
│   ├── backend-dev (Project)
│   │   ├── PostgreSQL
│   │   └── Redis
│   └── backend-prod (Project)
│       ├── PostgreSQL
│       └── Redis
├── Analytics Unit  
│   └── data-warehouse (Project)
│       ├── ClickHouse
│       └── Kafka
└── finance-prod (Project)
    └── PostgreSQL

Watch our video overview on organizations, units, and projects.

Organizations

When you sign up for Aiven, an organization is automatically created for you. Organizations are the top-level entity and provide centralized management for:

Centralized settings

Billing

Managed only at organization level

Billing groups shared across all units and projects
Payment methods and invoices
Billing addresses and tax information
Cannot be shared between organizations

Users & Groups

Organization-wide management

Organization users and application users
User groups for access management
Roles and permissions
User lifecycle management

Authentication

Security policies

Verified domains
SAML identity providers (IdPs)
Authentication policies
Two-factor authentication requirements

Support

Support tier

Applies to entire organization
Cannot be shared between organizations
Business, Advanced, or Premium tiers

Managing organizations

View organization details

Click Admin → Organization in the Aiven Console

Organization settings

Configure organization name, domains, identity providers, and authentication policies

Best practice

It’s recommended to have one Aiven organization per company for simplified management

Only Super Admin can delete organizations or rename them. Organization Admin has full access except for these operations.

Organizational units

Organizational units are collections of projects that help you group resources by department, environment, or any logical grouping.

Common use cases

By Department

Finance
Engineering
Marketing
Operations

By Environment

Development
Testing/QA
Staging
Production

Unit characteristics

Flat structure - Units cannot be nested within other units
Inherited settings - Organization-level settings apply to all units
Access control - Grant roles and permissions at the unit level
Unlimited units - Create as many units as needed

Creating organizational units

Using the Aiven CLI:

# Create an organizational unit
avn organization unit create \
  --organization-id <ORG_ID> \
  --unit-name "Production"

# List all units in an organization  
avn organization unit list --organization-id <ORG_ID>

# Delete an organizational unit
avn organization unit delete \
  --organization-id <ORG_ID> \
  --unit-id <UNIT_ID>

You cannot configure verified domains, billing groups, or identity providers at the unit level. These are managed only at the organization level.

Projects

Projects are collections of services that share common network and access settings. Projects can be created directly in an organization or within organizational units.

Project benefits

Service grouping - Organize related services together
Uniform security - Apply consistent network settings across all services
Access control - Grant team members project-level access
Billing assignment - Assign projects to billing groups

Project organization patterns

Single Project
Environment-Based
Application-Based

Best for: Small teams or simple deploymentsOne project with all services distinguished by naming:

my-project
├── postgres-prod
├── postgres-staging
├── redis-prod
└── redis-staging

Best for: Separating environments clearlyEach project represents a deployment environment:

dev (Project)
├── postgres
└── redis

qa (Project)  
├── postgres
└── redis

production (Project)
├── postgres
└── redis

Best for: Microservices or multiple applicationsEach project contains services for one application:

customer-api-prod (Project)
├── postgres
└── redis

analytics-pipeline-prod (Project)
├── kafka
└── clickhouse

Managing projects

Create a project

# Using Aiven CLI
avn project create \
  --organization-id <ORG_ID> \
  --project my-project

# Create in an organizational unit
avn project create \
  --organization-id <ORG_ID> \
  --parent-id <UNIT_ID> \
  --project my-project

Assign billing group

avn project update \
  --project my-project \
  --billing-group-id <BILLING_GROUP_ID>

Configure network settings

Set up VPCs, IP allowlists, and other network configurations that apply to all services in the project

Grant access

Assign users and groups project-level roles and permissions

Moving projects

You can move projects between organizational units or directly under the organization:

# Move project to an organizational unit
avn project move \
  --project my-project \
  --target-organization-id <ORG_ID> \
  --target-parent-id <UNIT_ID>

# Move project directly under organization
avn project move \
  --project my-project \
  --target-organization-id <ORG_ID>

Moving projects does not affect running services. The project retains its billing group assignment.

Best practices

Small organizations (1-10 services)

Keep it simple

Consolidate all projects within one organization without organizational units

Use naming conventions

Include environment in project names: backend-dev, backend-prod

Project-level permissions

Grant access at the project level to control who can access which services

Medium organizations (10-50 services)

Use organizational units

Group projects by department or environment using organizational units

Create user groups

Assign permissions to groups instead of individual users

Environment separation

Separate development and production into different units for clear boundaries

Large organizations (50+ services)

Mandatory organizational units

Keep all projects in organizational units, none directly under the organization

Standardize naming

Establish clear naming conventions for units and projects across the organization

Group-based access

Add all users to groups representing roles. Assign permissions at project or unit level

Restrict organization admins

Limit the number of super admins and organization admins for security

Granular billing permissions

Use billing-specific permissions to give finance team access without full admin rights

Domain verification

Verify your domain and configure authentication policies

Use Infrastructure as Code

Manage complex infrastructure with Aiven Terraform Provider

resource "aiven_organizational_unit" "prod" {
  name   = "Production"
  parent_id = aiven_organization.main.id
}

resource "aiven_project" "backend_prod" {
  project    = "backend-prod"
  parent_id  = aiven_organizational_unit.prod.id
}

Bring Your Own Cloud (BYOC)

For organizations with specific compliance or infrastructure requirements, Aiven offers BYOC deployment:

What is BYOC?

BYOC allows you to run Aiven-managed services in your own cloud account while maintaining the Aiven user experience.

Benefits

Use existing cloud commitments and discounts
Enhanced network visibility and control
Meet strict compliance requirements
Audit network metadata in your account

Requirements

AWS or Google Cloud account
Commitment deal with Aiven
Advanced or Premium support tier
Custom pricing arrangement

BYOC architecture

BYOC services run in custom clouds within your cloud provider account:

Your AWS/GCP Account
└── Custom Cloud (BYOC VPC)
    ├── Bastion Host (private deployments)
    ├── Service VMs (Aiven-managed)
    └── S3/GCS Buckets (backups & cold storage)
    
Aiven Management Plane
└── Service orchestration and monitoring

Deployment models

Private Deployment
Public Deployment

Services in private subnet, accessed via bastion host:

Service VMs not publicly accessible
Aiven connects through bastion from static IP
Most secure option

Getting started with BYOC

Contact Aiven sales

Schedule a call to discuss your use case and requirements

Enable BYOC

Aiven enables BYOC capability for your organization

Create custom cloud

# Generate infrastructure template
avn byoc create \
  --organization-id <ORG_ID> \
  --deployment-model private \
  --cloud-provider aws \
  --region us-east-1

Deploy template

Apply the generated CloudFormation (AWS) or Terraform (GCP) template in your cloud account

Deploy services

Create services in your custom cloud like any other Aiven service

BYOC adds complexity to service management, key management, and networking. Consider standard Aiven deployment or Enhanced Compliance Environment first. Contact your account team to determine the best fit.

API reference

Manage organizations, units, and projects programmatically:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.aiven.io/v1/organization

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "parent_id": "org123"
  }' \
  https://api.aiven.io/v1/organization/{org_id}/unit

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-project",
    "parent_id": "unit123"
  }' \
  https://api.aiven.io/v1/organization/{org_id}/projects

curl -H "Authorization: Bearer $TOKEN" \
  https://api.aiven.io/v1/project/{project}

Next steps

Billing & Payment

Configure billing groups and payment methods

Users & Permissions

Set up team members and access control

Authentication

Configure SSO and authentication policies

VPC Networking

Set up private connectivity with VPC peering

​Hierarchy overview

Organization

Organizational Unit

Project

​Example structure

​Organizations

​Centralized settings

Billing

Users & Groups

Authentication

Support

​Managing organizations

​Organizational units

​Common use cases

By Department

By Environment

​Unit characteristics

​Creating organizational units

​Projects

​Project benefits

​Project organization patterns

​Managing projects

​Moving projects

​Best practices

​Small organizations (1-10 services)

​Medium organizations (10-50 services)

​Large organizations (50+ services)

​Bring Your Own Cloud (BYOC)

​What is BYOC?

Benefits

Requirements

​BYOC architecture

​Deployment models

​Getting started with BYOC

​API reference

​Next steps

Billing & Payment

Users & Permissions

Authentication

VPC Networking

Hierarchy overview

Example structure

Organizations

Centralized settings

Managing organizations

Organizational units

Common use cases

Unit characteristics

Creating organizational units

Projects

Project benefits

Project organization patterns

Managing projects

Moving projects

Best practices

Small organizations (1-10 services)

Medium organizations (10-50 services)

Large organizations (50+ services)

Bring Your Own Cloud (BYOC)

What is BYOC?

BYOC architecture

Deployment models

Getting started with BYOC

API reference

Next steps