Organizaciones

Las organizaciones son las entidades de nivel superior en Capgo. Permiten agrupar aplicaciones, miembros del equipo y recursos bajo un solo paraguas. Cada organización puede tener varios miembros con roles y permisos diferentes.

Casos de Uso Comunes

• Crear una nueva organización para su empresa
• Gestionar ajustes de organización
• Actualizar información de organización
• Obtener detalles de organización

Puntos finales

GET

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

Obtener información de la organización. Si orgId se proporciona en los parámetros, devuelve una organización única. De lo contrario, devuelve todas las organizaciones accesibles.

Parámetros de consulta

• orgId (opcional): El ID de la organización específica a recuperar

Tipo de respuesta

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
}

Ejemplo de Solicitud

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

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

Ejemplo de respuesta

{
  "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/

Crear una nueva organización.

Cuando se utiliza una clave API, la clave debe tener el alcance global org.create permiso y una organización actual org_admin or org_super_admin La organización destino no existe aún, por lo que no se puede verificar la RBAC normalmente contra ella.

Cuando la solicitud tiene éxito, Capgo asigna automáticamente la misma clave de API org_super_admin en la nueva organización.

Nota

org.create No se concede por defecto a las nuevas claves de API. Active Permitir crear organizaciones en la forma de clave de API, o incluya "global_permissions": ["org.create"] cuando se crea la clave a través de API.

Cuerpo de la solicitud

interface OrganizationCreate {
  name: string
  email?: string
  estimatedMau?: number
  website?: string
}

Solicitud de ejemplo

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Organization",
    "email": "admin@example.com",
    "website": "https://example.com"
  }' \
  https://api.capgo.app/organization/

Respuesta de ejemplo

{
  "id": "org_456"
}

Error de permiso

Si la clave API no tiene org.create, el API devuelve:

{
  "error": "permission_denied"
}

PUT

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

Actualizar una organización existente. Requiere el rol de administrador en la organización objetivo.

Cuerpo de la solicitud

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

Ejemplo de solicitud

curl -X PUT \
  -H "x-api-key: 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/

Sección titulada “Ejemplo de respuesta”

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

DELETE

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

Eliminar una organización existente. Requiere permiso de eliminación en la organización objetivo, típicamente a través del org_super_admin rol. Esta acción es irreversible y eliminará todos los aplicativos asociados, conjuntos (versiones) y recursos.

El org.create permiso global no permite eliminar organizaciones.

Parámetros de consulta

• orgId: El ID de la organización a eliminar

Solicitud de ejemplo

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

Respuesta de ejemplo

{
  "status": "ok"
}

Manejo de errores

Escenarios de errores comunes y sus respuestas:

// 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"
}

Prácticas recomendadas

1. Nomenclatura: Utilice nombres claros y descriptivos para organizaciones
2. Roles: Asignar roles adecuados a los miembros del equipo
3. Email: Utilice un correo electrónico grupal para evitar problemas con cambios de correo electrónico personal
4. Logo: Almacene logos en un CDN confiable y utilice URLs HTTPS

Seguir adelante desde Organizaciones

Organizaciones Organizations planificar la consola y las operaciones API, conectarla con Resumen de API para los detalles de implementación en API Resumen Introducción para los detalles de implementación en Introducción API Claves para los detalles de implementación en API Claves Dispositivos para los detalles de implementación en dispositivos Bundles para los detalles de implementación en Paquetes.