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.