Create and Link Client Organisations

Published · Last updated: May 2026 · 4 min read

Who this is for

Agency account owners or staff with the client:manage permission who are onboarding a new client onto the CloudAIPilot agency platform.

What you will complete

You will add a client to your agency — either by creating a brand-new organisation for them, or by linking an existing CloudAIPilot organisation they already own. You will also configure the client's contact details and tags.

Before you begin

Your billing account must be an Agency-tier account (Agency section is visible in your sidebar).
You must have the agency:manage or client:manage permission on the agency billing account.
If linking an existing org: the org owner must provide their Organisation ID (found in their org settings).

Option A — Create a new client organisation

Use this path when your client does not have an existing CloudAIPilot account.

Step 1 — Open the Agency dashboard. In the left sidebar, click Agency. The agency overview loads showing your client list.

Step 2 — Click Add Client. The "Add Client" button is in the top-right of the client list panel.

Step 3 — Select Create new organisation. A form opens with fields for the new org and client record.

Step 4 — Fill in the organisation details.

Organisation name: The internal name for the new org (e.g. "Acme Corp"). This is what appears in the org switcher.
Client display name: The name shown in your agency dashboard for this client (can be different from the org name).
Contact name, Contact email, Contact phone: Optional. Stored on the client record for your reference.
Notes: Internal notes visible only to agency staff.
Tags: Up to 20 tags for filtering and categorisation (e.g. tier:gold, region:eu).

Step 5 — Click Create client. CloudAIPilot creates the new organisation and automatically links it to your agency billing account. The new org appears in your client list immediately.

Result checkpoint: You should see the new client in your client list with status Active. You can now add the client's cloud accounts, provision servers, and configure white-label branding.

Option B — Link an existing organisation

Use this path when your client already has a CloudAIPilot account and wants to bring their existing infrastructure under your agency management.

Step 1 — Open the Agency dashboard and click Add Client.

Step 2 — Select Link existing organisation.

Step 3 — Enter the client's Organisation ID. The client finds this in: Settings → Organisation → Organisation ID. It is a UUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Step 4 — Fill in the client details (display name, contact, notes, tags).

Step 5 — Click Link client. CloudAIPilot verifies the org exists and links it to your agency billing account.

Result checkpoint: The client appears in your list with status Active. Their existing servers, sites, and data are immediately visible in your cross-org views.

Important: Linking an existing org does not transfer billing. The client's org retains its own billing relationship with CloudAIPilot unless you explicitly move them to your agency billing plan.

Edit client details after linking

In the client list, click the client name.
Click the Edit button (pencil icon) at the top of the client detail panel.
Update contact details, notes, or tags as needed.
Click Save.

Common errors

"Organisation not found" when linking by ID Cause: The ID entered is incorrect or the org does not exist. Fix: Ask the client to copy the ID directly from Settings → Organisation to avoid typos.

"Already linked" error Cause: The org is already linked to this or another agency billing account. Fix: An org can only belong to one agency at a time. Email support@cloudaipilot.com if the link is from a previous agency relationship.

Client created but not visible in cross-org views Cause: The client's org has no cloud accounts or servers connected yet. Fix: Add the client's cloud provider credentials from their org settings, or do it from the Agency > Clients > [client] > Cloud Accounts panel.

"Permission denied" creating a client Cause: Your agency staff role does not include client:manage. Fix: Ask the agency account owner to update your role in Agency > Staff.