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 diferentes roles y permisos.

Uso común

• Crear una nueva organización para tu empresa
• Administrar ajustes de organización
• Actualizar información de organización
• Obtener detalles de organización

Puntos de conexión

GET

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

Recuperar información de la organización. Si se proporciona en los parámetros, devuelve una sola organización. De lo contrario, devuelve todas las organizaciones accesibles. orgId Parámetros de consulta

Sección titulada “Parámetros de consulta”

• orgId Tipo de respuesta

Sección titulada “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 permiso global y una organización-scoped actualmente configurado. org.create Section titled “POST”]} // Removed the extra item to match the 12 string requirement. The extra item was org_admin o org_super_admin de vinculación. Esto es necesario porque la organización objetivo no existe todavía, por lo que la RBAC normalmente escopada a la organización no puede ser verificada contra ella.

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

Nota

org.create no se le concede por defecto a las nuevas claves API. Habilitar Permitir la creación de organizaciones en la forma de clave API, o incluir "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.createel valor de la clave API devuelve:

{
  "error": "permission_denied"
}

PUT

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

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

Cuerpo de la solicitud

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

Solicitud de ejemplo

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/

Respuesta de ejemplo

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

ELIMINAR

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 . Esta acción es irreversible y eliminará todas las aplicaciones asociadas, conjuntos (versiones) y recursos.

El org.create permiso global no permite eliminar organizaciones.

Parámetros de consulta

• orgIdEl 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"
}

Gestión 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: Asigne roles adecuados a los miembros del equipo
3. Correo electrónico: Utilice un correo electrónico de grupo para management_email para evitar problemas con cambios de correo electrónico personal
4. Logo: Almacene logos en un CDN confiable y utilice URLs HTTPS

Siga adelante desde Organizaciones

Si está utilizando Organizaciones para planificar la consola y las operaciones de API, conecte con API Resumen 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, y Paquetes para los detalles de implementación en Paquetes.