Create a new organization

Creates a new organization with the specified configuration. Organizations serve as the top-level container for all resources including environments, packages, workspaces, and user groups.

Authorization (two paths):

• Direct create. Default. Requires the system-level can_create_organization permission.
• Invite redemption. Supply the raw invite token in the X-Invite-Token header. The invite is the authorization — any authenticated user may redeem. The caller is granted admin on the new organization, the caller’s user row is ensured, MPA acceptance is recorded (using the server’s current MPA version), and the invite is marked consumed. If the invite was minted with a boundEmail, the caller’s email must match (case-insensitive). If the token has already been redeemed, a 409 is returned naming the prior organization.

Error codes. On 4xx the response body carries an Error { code, message }. Clients should branch on code:

Status	code	Meaning
400	VALIDATION_ERROR	Body field validation failed (e.g. bad displayName).
400	INVITE_INVALID	X-Invite-Token is malformed or unknown.
400	INVITE_EXPIRED	X-Invite-Token is past its expiresAt.
403	INSUFFICIENT_PERMISSIONS	Direct create attempted without the required permission.
403	INVITE_EMAIL_MISMATCH	Invite is bound to a different email than the caller.
409	ORGANIZATION_NAME_TAKEN	Requested name (URL slug) is taken — retry with another.
409	ORGANIZATION_NAME_RESERVED	Requested name collides with a platform subdomain.
409	INVITE_ALREADY_CONSUMED	Token was already redeemed; retry will not help.

Validation: Organization names must be unique and follow naming conventions. Side Effects: Creates default permissions and initializes organizational structure.

POST /organizations

Create a new organization

cURL

curl --request POST \
  --url https://{organization}.admin.credibledata.com/api/v0/organizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "displayName": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}
'

200

{
  "name": "<string>",
  "displayName": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "mpaVersion": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Invite-Token · string

Raw invite token (e.g. ABCDE-FGHJK). When supplied, the system-level can_create_organization permission check is bypassed — the invite is the authorization. Required for self-serve signup; omit for direct-create by privileged users.

Body

application/json

Represents an organization entity that serves as the top-level container for all resources

name · string

The unique identifier for the organization. Used as the resource name in API paths AND as the DNS subdomain label routing traffic to the org, so it follows RFC 1035 hostname rules — lowercase letters, digits, and hyphens; no underscores; no leading or trailing hyphen; max 63 chars.

Required string length: 1 - 63

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

displayName · string

Human-readable name for the organization, displayed in user interfaces

Required string length: 1 - 128

Pattern: ^[^\u0000-\u001F\u007F]+$

createdAt · string<date-time>

ISO 8601 timestamp indicating when the organization was created

updatedAt · string<date-time>

ISO 8601 timestamp indicating when the organization was last modified

Response

200

application/json

Organization created successfully

Represents an organization entity that serves as the top-level container for all resources

name · string

The unique identifier for the organization. Used as the resource name in API paths AND as the DNS subdomain label routing traffic to the org, so it follows RFC 1035 hostname rules — lowercase letters, digits, and hyphens; no underscores; no leading or trailing hyphen; max 63 chars.

Required string length: 1 - 63

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$

displayName · string

Human-readable name for the organization, displayed in user interfaces

Required string length: 1 - 128

Pattern: ^[^\u0000-\u001F\u007F]+$

createdAt · string<date-time>

ISO 8601 timestamp indicating when the organization was created

updatedAt · string<date-time>

ISO 8601 timestamp indicating when the organization was last modified

mpaVersion · string · read-only

Version identifier of the Master Platform Agreement the organization accepted at creation time (file basename, e.g. v1-2026-05-19). Server-set: clients do not (and cannot) submit this field — when an organization is created via the invite-redemption path, the server stamps its current active MPA version. Null on legacy organizations created before MPA acceptance was required.

Only the version is exposed on this resource. The per-user / per- timestamp audit fields (mpa_accepted_by, mpa_accepted_at) are kept internal — useful for compliance audit on the server side, not for API consumers. If a future use case needs them on the API, add them then; widening is easier than narrowing.

Required string length: 1 - 32

Pattern: ^[a-zA-Z0-9._-]+$