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.