Skip to main content
POST
/
workspaces
/
{workspaceId}
/
organizations
Create an organization
curl --request POST \
  --url https://api.altostrat.io/workspaces/{workspaceId}/organizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Marketing Team",
  "billing_account_id": "cus_a1b2c3d4e5f6g7h8",
  "limits": {
    "locations": 5,
    "users": 20
  },
  "picture": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  "branding": {
    "display_name": "ACME Inc.",
    "login_hint": "acme-inc",
    "colors": {
      "primary": "#007bff"
    }
  }
}'
{
  "id": "org_aBcDeFg123456789",
  "name": "Engineering Department",
  "workspace_id": "ws_a1b2c3d4e5f6g7h8",
  "external_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "parent_org_id": "org_zYxWvUt987654321",
  "path": "org_root123#org_parent456",
  "depth": 2,
  "billing_account_id": "cus_a1b2c3d4e5f6g7h8",
  "picture": "https://cdn.altostrat.io/logos/engineering.png",
  "usage": {
    "usage": {
      "locations": 2,
      "users": 5
    },
    "subtree_usage": {
      "locations": 10,
      "users": 25
    }
  },
  "limits": {
    "locations": 10,
    "users": 50
  },
  "branding": {
    "display_name": "ACME Corp",
    "login_hint": "acme-corp",
    "colors": {
      "primary": "#FF5733",
      "page_background": "#FFFFFF"
    }
  }
}

Authorizations

โ€‹
Authorization
string
header
required

Enter your JWT in the format: Bearer {token}

Path Parameters

โ€‹
workspaceId
string
required

The ID of the workspace.

Example:

"ws_a1b2c3d4e5f6g7h8"

Body

application/json
โ€‹
name
string
required

The name of the organization. Maximum 50 characters.

Example:

"Marketing Team"

โ€‹
billing_account_id
string | null

The ID of the billing account to associate. Required for root organizations in single or assigned billing modes. Must be null for child organizations or any organization in pooled mode.

Example:

"cus_a1b2c3d4e5f6g7h8"

โ€‹
limits
object

Set resource limits for the organization. Keys are meterable types (locations, users, sso). A value of null removes the limit, 0 disables the resource.

Example:
{ "locations": 5, "users": 20 }
โ€‹
picture
string | null

A public HTTPS URL to an image or a base64 encoded data URI. The image will be processed and hosted by Altostrat. Must be a JPEG, PNG, or GIF under 2MB.

Example:

"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."

โ€‹
branding
object

Branding settings for the organization.

Response

The organization was created successfully.

โ€‹
id
string

Unique identifier for the organization (corresponds to Auth0 organization ID), prefixed with org_.

Example:

"org_aBcDeFg123456789"

โ€‹
name
string

The human-readable name of the organization.

Example:

"Engineering Department"

โ€‹
workspace_id
string

The ID of the workspace this organization belongs to.

Example:

"ws_a1b2c3d4e5f6g7h8"

โ€‹
external_id
string<uuid>

A stable, unique identifier for the organization, independent of its Auth0 ID.

Example:

"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"

โ€‹
parent_org_id
string | null

The ID of the parent organization, if this is a child organization.

Example:

"org_zYxWvUt987654321"

โ€‹
path
string | null

A #-separated string representing the hierarchical path of ancestors.

Example:

"org_root123#org_parent456"

โ€‹
depth
integer

The depth of the organization in the hierarchy (0 for top-level).

Example:

2

โ€‹
billing_account_id
string | null

The ID of the billing account this organization is associated with (in assigned mode).

Example:

"cus_a1b2c3d4e5f6g7h8"

โ€‹
picture
string<uri> | null

A URL to the organization's logo.

Example:

"https://cdn.altostrat.io/logos/engineering.png"

โ€‹
usage
object
โ€‹
limits
object

A map of resource limits applied directly to this organization. Keys are meterable types (locations, users, sso). A value of null or a missing key means no limit is set at this level. A value of 0 means the resource is explicitly disabled.

Example:
{ "locations": 10, "users": 50 }
โ€‹
branding
object