Organization Management

Create, read, list, and update the organizations a user belongs to in the Blue API.

An organization is the top-level tenant in Blue — it owns workspaces, members, billing, and branding. Organizations are Company objects in the API, and every authenticated request runs inside exactly one of them, selected by the X-Bloo-Company-ID header.

This section covers the organization lifecycle a normal API consumer can drive: create an organization, read one, list the organizations the calling user belongs to, update an organization’s profile, and check whether a slug is free. For adding and removing members, see User Management.

Operations

OperationGraphQLDescription
Create an organizationcreateCompanyCreate a new organization with a name and slug; the caller becomes its OWNER.
Get an organizationcompany(id)Read a single organization by ID or slug.
List organizationscompanies(filter, sort, skip, take)Page through the organizations the calling user is a member of. Returns CompanyPagination ({ items, pageInfo }).
Update an organizationeditCompany(input)Update an organization’s name, slug, image, white-label settings, and other profile fields. Requires OWNER access.
Check slug availabilityisCompanySlugAvailable(slug)Returns true if no organization already uses that exact slug.

Membership and lifecycle operations live alongside these: leaveCompany (leave an organization you belong to), removeCompanyUser (remove another member), and deleteCompanyRequest (request deletion of an organization). See User Management for member operations.

Authentication

Send every request to https://api.blue.cc/graphql with your personal access token headers:

X-Bloo-Token-ID: YOUR_TOKEN_ID
X-Bloo-Token-Secret: YOUR_TOKEN_SECRET
X-Bloo-Company-ID: YOUR_COMPANY_ID

X-Bloo-Company-ID accepts an organization ID or its slug, and it sets the organization context for the whole request. See Authentication for how to obtain a token and Making Requests for the full request shape. Headers are case-insensitive.

Key concepts

Identifying an organization

Every organization has two stable identifiers, and operations that take an organization accept either:

  • ID — a unique cuid generated by Blue when the organization is created. Returned as Company.id.
  • Slug — a URL-friendly string. You propose the slug when creating an organization, but Blue normalizes it server-side (lowercased, symbols stripped, spaces replaced with hyphens) and appends a numeric suffix on collision. The final stored slug is returned on the created Company and may differ from what you submitted. Use isCompanySlugAvailable to check a candidate before you create, or read Company.slug afterward to learn the value that was actually stored.

Access control

  • A user can only read organizations they are a member of. company and companies resolve against the caller’s memberships; requesting an organization you don’t belong to returns COMPANY_NOT_FOUND.
  • editCompany requires OWNER access to the target organization; other members get FORBIDDEN.
  • If the organization set in your X-Bloo-Company-ID header is banned, every request in that context fails with COMPANY_BANNED. The ban is enforced when the request context is built from the header — it is not a check performed by the company read path on some other target organization.
Billing is per organization

Each organization is billed separately. Creating organizations through the API can affect your account’s billing.