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 Organization 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 organizationcreateOrganizationCreate a new organization with a name and slug; the caller becomes its OWNER.
Get an organizationorganization(id)Read a single organization by ID or slug.
List organizationsorganizations(filter, sort, skip, take)Page through the organizations the calling user is a member of. Returns OrganizationPagination ({ items, pageInfo }).
Update an organizationeditOrganization(input)Update an organization’s name, slug, image, white-label settings, and other profile fields. Requires OWNER access.
Check slug availabilityisOrganizationSlugAvailable(slug)Returns true if no organization already uses that exact slug.

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

Authentication

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

blue-token-id: YOUR_TOKEN_ID
blue-token-secret: YOUR_TOKEN_SECRET
blue-org-id: YOUR_ORG_ID

blue-org-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 Organization.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 Organization and may differ from what you submitted. Use isOrganizationSlugAvailable to check a candidate before you create, or read Organization.slug afterward to learn the value that was actually stored.

Access control

  • A user can only read organizations they are a member of. organization and organizations resolve against the caller’s memberships; requesting an organization you don’t belong to returns COMPANY_NOT_FOUND.
  • editOrganization 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 organization 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.