Organizations

Organizations are the top-level entities in Capgo. They allow you to group apps, team members, and resources under a single umbrella. Each organization can have multiple members with different roles and permissions.

Common Use Cases

• Creating a new organization for your company
• Managing organization settings
• Updating organization information
• Retrieving organization details

Endpoints

GET

https://api.capgo.app/organization/

Retrieve organization information. If orgId is provided in the parameters, returns a single organization. Otherwise, returns all accessible organizations.

Query Parameters

• orgId (optional): The ID of the specific organization to retrieve

Response Type

interface Organization {
  id: string
  created_by: string
  created_at: string
  updated_at: string
  logo: string | null
  name: string
  management_email: string
  customer_id: string | null
}

Example Request

# Get all organizations
curl -H "authorization: your-api-key" https://api.capgo.app/organization/

# Get specific organization
curl -H "authorization: your-api-key" https://api.capgo.app/organization/?orgId=org_123

Example Response

{
  "data": {
    "id": "org_123",
    "name": "My Company",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "logo": "https://example.com/logo.png",
    "management_email": "admin@example.com",
    "customer_id": "cus_123"
  }
}

POST

https://api.capgo.app/organization/

Create a new organization.

Request Body

interface OrganizationCreate {
  name: string
}

Example Request

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Organization"
  }' \
  https://api.capgo.app/organization/

Example Response

{
  "status": "Organization created",
  "id": "org_456"
}

PUT

https://api.capgo.app/organization/

Update an existing organization. Requires admin role.

Request Body

interface OrganizationUpdate {
  orgId: string
  logo?: string
  name?: string
  management_email?: string
}

Example Request

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "name": "New Company Name",
    "management_email": "newemail@example.com"
  }' \
  https://api.capgo.app/organization/

Example Response

{
  "status": "Organization updated",
  "data": {
    "id": "org_123",
    "name": "New Company Name",
    "management_email": "newemail@example.com"
  }
}

DELETE

https://api.capgo.app/organization/

Delete an existing organization. Requires admin role. This action is irreversible and will remove all associated apps, bundles (versions), and resources.

Query Parameters

• orgId: The ID of the organization to delete

Example Request

curl -X DELETE \
  -H "authorization: your-api-key" \
  https://api.capgo.app/organization/?orgId=org_123

Example Response

{
  "status": "Organization deleted",
  "id": "org_123"
}

Error Handling

Common error scenarios and their responses:

// Invalid API key
{
  "error": "Invalid API key",
  "status": "KO"
}

// Missing required field
{
  "error": "Name is required",
  "status": "KO"
}

// Insufficient permissions
{
  "error": "Admin role required",
  "status": "KO"
}

Best Practices

1. Naming: Use clear, descriptive names for organizations
2. Roles: Assign appropriate roles to team members
3. Email: Use a group email for management_email to avoid issues with personal email changes
4. Logo: Host logos on a reliable CDN and use HTTPS URLs

Keep going from Organizations

If you are using Organizations to plan dashboard and API operations, connect it with API Overview for the implementation detail in API Overview, Introduction for the implementation detail in Introduction, API Keys for the implementation detail in API Keys, Devices for the implementation detail in Devices, and Bundles for the implementation detail in Bundles.