Skip to main content
Create a new organization. The authenticated user automatically becomes the owner/admin of the newly created organization.

​
Request Body

​
body
object
required
Organization details to create.
​
name
string
required
Unique name/slug for the organization. Must be lowercase, alphanumeric with hyphens. Used in URLs and API calls. Cannot be changed after creation.Example: acme-corp, my-organization
​
title
string
required
Human-readable display name for the organization. Can contain spaces and special characters.Example: Acme Corporation, My Organization
​
avatar
string
URL to the organization’s avatar image. Should be a publicly accessible image URL.Example: https://example.com/avatars/acme.png
​
metadata
object
Custom metadata for the organization. Can contain any valid JSON structure. Must comply with the organization metadata schema if validation is enabled.Example: {"industry": "technology", "size": "enterprise", "region": "us-west"}

​
Response

​
organization
object
The newly created organization object.
​
id
string
Unique identifier for the organization (UUID format).
​
name
string
Unique name/slug for the organization.
​
title
string
Human-readable display name for the organization.
​
avatar
string
URL to the organization’s avatar image.
​
state
string
State of the organization. Newly created organizations are enabled by default.
​
metadata
object
Custom metadata associated with the organization.
​
created_at
timestamp
Timestamp when the organization was created (RFC3339 format).
​
updated_at
timestamp
Timestamp when the organization was last updated (RFC3339 format).
curl -X POST 'https://api.frontier.example.com/v1beta1/organizations' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "body": {
      "name": "acme-corp",
      "title": "Acme Corporation",
      "avatar": "https://example.com/avatars/acme.png",
      "metadata": {
        "industry": "technology",
        "size": "enterprise"
      }
    }
  }'

​
Response Example

{
  "organization": {
    "id": "9f256f86-d3c4-4a6e-b89a-1e9a23c5d78e",
    "name": "acme-corp",
    "title": "Acme Corporation",
    "avatar": "https://example.com/avatars/acme.png",
    "state": "enabled",
    "metadata": {
      "industry": "technology",
      "size": "enterprise"
    },
    "created_at": "2024-03-03T10:30:00Z",
    "updated_at": "2024-03-03T10:30:00Z"
  }
}

​
Error Responses

​
code
string
Error code indicating the type of error.
​
message
string
Human-readable error message.

​
Common Errors

  • 400 Bad Request: Invalid request body or missing required fields
    • Invalid organization name format (must be lowercase alphanumeric with hyphens)
    • Metadata doesn’t match the required schema
    • Missing required fields (name or title)
  • 401 Unauthenticated: Invalid or missing authentication token
  • 409 Conflict: Organization with the same name already exists
  • 500 Internal Server Error: Server encountered an unexpected error

​
Notes

  • The authenticated user automatically becomes the organization owner
  • Organization names are globally unique and cannot be changed
  • The organization is created in enabled state by default
  • An audit log entry is created for the organization creation event
  • Default roles and permissions are automatically set up for the owner

Build docs developers (and LLMs) love

Get started for freeTalk to us