Planned feature : The endpoints described on this page are part of the planned API design and are not yet implemented in the current codebase.
The planned Organizations API will allow you to create and retrieve organizations within your multi-tenant platform. Organizations will serve as the top-level container for users, roles, and resources.
Authentication All organization endpoints require authentication using a JWT bearer token in the Authorization header:
Authorization: Bearer YOUR_JWT_TOKEN
Get organizations This endpoint returns all organizations accessible to the authenticated user based on their permissions.
Retrieves a list of organizations. You can filter, sort, and paginate the results using query parameters.
Query parameters The page number for pagination
Number of organizations to return per page (maximum 100)
sort
string
default: "createdAt"
Field to sort by. Options: name, createdAt, updatedAt
Sort order. Options: asc, desc
Search organizations by name or domain
Filter by organization status. Options: active, suspended, archived
Response Array of organization objects Unique identifier for the organization (UUID)
URL-friendly identifier for the organization
Primary domain associated with the organization
Current status of the organization. Options: active, suspended, archived
Organization-specific settings and configuration Whether public signup is enabled
Whether email verification is required for new users
Default role assigned to new members
Custom metadata key-value pairs
ISO 8601 timestamp when the organization was created
ISO 8601 timestamp when the organization was last updated
Pagination metadata Total number of organizations
Example request curl -X GET "https://api.orgstack.io/api/organizations?page=1&limit=10&status=active" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json"
Example response { "data" : [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Acme Corporation" , "slug" : "acme-corp" , "domain" : "acme.com" , "status" : "active" , "settings" : { "allowPublicSignup" : true , "requireEmailVerification" : true , "defaultRole" : "member" }, "metadata" : { "industry" : "Technology" , "size" : "enterprise" }, "createdAt" : "2024-01-15T08:30:00.000Z" , "updatedAt" : "2024-02-20T14:22:00.000Z" }, { "id" : "6ba7b810-9dad-11d1-80b4-00c04fd430c8" , "name" : "TechStart Inc" , "slug" : "techstart" , "domain" : "techstart.io" , "status" : "active" , "settings" : { "allowPublicSignup" : false , "requireEmailVerification" : true , "defaultRole" : "viewer" }, "metadata" : { "industry" : "SaaS" , "size" : "startup" }, "createdAt" : "2024-02-10T10:15:00.000Z" , "updatedAt" : "2024-02-28T16:45:00.000Z" } ], "pagination" : { "page" : 1 , "limit" : 10 , "total" : 2 , "totalPages" : 1 } }
{ "error" : { "code" : "UNAUTHORIZED" , "message" : "Invalid or missing authentication token" } }
{ "error" : { "code" : "FORBIDDEN" , "message" : "You do not have permission to access organizations" } }
Create organization Only users with admin privileges can create new organizations. The authenticated user will automatically become the owner of the newly created organization.
Creates a new organization in the system. The organization slug must be unique across the platform.
Request body Organization name (2-100 characters)
URL-friendly identifier (3-50 characters, lowercase letters, numbers, and hyphens only)
Primary domain for the organization (must be a valid domain)
Organization settings and configuration settings.allowPublicSignup
Enable public signup for the organization
settings.requireEmailVerification
Require email verification for new users
Default role for new members. Options: admin, member, viewer
Custom metadata as key-value pairs (optional)
Response Returns the created organization object with all fields populated, including generated id, createdAt, and updatedAt timestamps.
Unique identifier for the organization (UUID)
Organization status (default: active)
ISO 8601 timestamp when created
ISO 8601 timestamp when last updated
Example request curl -X POST "https://api.orgstack.io/api/organizations" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "name": "GlobalTech Solutions", "slug": "globaltech", "domain": "globaltech.com", "settings": { "allowPublicSignup": true, "requireEmailVerification": true, "defaultRole": "member" }, "metadata": { "industry": "Consulting", "region": "North America" } }'
Example response { "id" : "7c9e6679-7425-40de-944b-e07fc1f90ae7" , "name" : "GlobalTech Solutions" , "slug" : "globaltech" , "domain" : "globaltech.com" , "status" : "active" , "settings" : { "allowPublicSignup" : true , "requireEmailVerification" : true , "defaultRole" : "member" }, "metadata" : { "industry" : "Consulting" , "region" : "North America" }, "createdAt" : "2026-03-01T10:30:00.000Z" , "updatedAt" : "2026-03-01T10:30:00.000Z" }
{ "error" : { "code" : "VALIDATION_ERROR" , "message" : "Invalid request body" , "details" : [ { "field" : "slug" , "message" : "Slug must be 3-50 characters and contain only lowercase letters, numbers, and hyphens" } ] } }
{ "error" : { "code" : "UNAUTHORIZED" , "message" : "Invalid or missing authentication token" } }
{ "error" : { "code" : "FORBIDDEN" , "message" : "You do not have permission to create organizations" } }
{ "error" : { "code" : "CONFLICT" , "message" : "An organization with this slug already exists" } }
Error codes The Organizations API may return the following error codes:
Code Description UNAUTHORIZEDMissing or invalid authentication token FORBIDDENInsufficient permissions to perform the action VALIDATION_ERRORRequest body validation failed CONFLICTResource conflict (e.g., duplicate slug) NOT_FOUNDOrganization not found RATE_LIMIT_EXCEEDEDToo many requests, please retry later INTERNAL_ERRORUnexpected server error