Organization settings

What an organization stores, how to create one, and which fields are fixed for the life of the organization.

An organization is created from a name, and its slug is derived from that name. Neither can be changed afterwards, and an organization cannot be deleted.

The organization record

Field	Rules	Notes
`id`	UUID	The identifier every organization-scoped API takes
`name`	1 to 128 characters	Display name, set once at creation
`slug`	Up to 128 characters, unique	Derived from the name, used in Gigadrive console URLs
`imageUrl`	URL	A shared Gigadrive placeholder until an avatar is set
`createdAt`/`updatedAt`	ISO 8601 strings	Timestamps

How the slug is derived

The name is lowercased and trimmed, every run of characters outside a-z, 0-9 and - becomes a single -, repeated hyphens collapse, and leading or trailing hyphens are stripped. Acme Corp becomes acme-corp. If that slug is already taken, a five-character random suffix is appended, so you may end up with acme-corp-k3f9a.

You cannot choose the slug. POST /organizations accepts a name and nothing else.

Creating an organization

The authenticated user becomes the organization's OWNER. Creation is atomic, so a half-created organization without an owner is not a state you can land in.

import { GigadriveClient } from '@gigadrive/sdk';

// Only user-backed tokens can create an organization, so this needs an access
// token from Gigadrive IDP rather than an API key.
const client = new GigadriveClient({ bearerToken: process.env.GIGADRIVE_ACCESS_TOKEN });

const organization = await client.organizations.create({ name: 'Acme Corp' });
console.log(organization.id, organization.slug);

The endpoint requires the platform:organizations:write scope and a USER actor. Organization, application, deployment and function tokens are refused with 403, because a machine credential has no person to make the owner. See Scopes for how actors and scopes interact.

Creation limits

Limit	Value	What it counts
Organizations you can own	10	Memberships where you are `OWNER`. `ADMIN` and `MEMBER` do not count.
Organizations you can own without billing	2	Owned organizations with no saved payment method
Creation attempts	5 per hour	Per user. Attempts the quotas then reject still consume the window.

An organization stops counting against the second limit as soon as it has a default payment method, so adding one to an existing organization frees a slot immediately. The checks run in order: rate limit first, then the ownership quota, then the unverified-billing budget.

Past two unverified organizations, use the console

POST /organizations returns 403 once you own two organizations without billing, because the API has no payment form to offer. The Gigadrive console asks for a payment method first and creates the organization only after it is saved. See Payment methods.

What cannot be changed

There is no rename, no slug change, no delete, and no ownership transfer. The organization API is create and read only. If a name is wrong, create a new organization and move work across.

Settings in the console

An organization has three settings pages, and none of them edit the organization record itself:

Variables sets environment variables shared by every application in the organization.
Limits shows each resource quota with live usage against it, so you can see where you stand before an enforcement error. See Quotas.
Billing holds the plan, seats, budget, billing address and payment method. See Billing.