Organizaciones

Las organizaciones son las entidades de nivel superior en Capgo. Te permiten agrupar apps, miembros del equipo y recursos bajo un mismo paraguas. Cada organización puede tener varios miembros con distintos roles y permisos.

Casos de uso comunes

• Crear una nueva organización para tu empresa
• Gestionar la configuración de la organización
• Actualizar la información de la organización
• Obtener los detalles de la organización

Endpoints

GET

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

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

Parámetros de consulta

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

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/

Crea una nueva organización.

Al usar una clave API, esta debe tener el permiso org.create permiso y un ámbito de organización actual org_admin o org_super_admin vinculación. Esto es necesario porque la organización de destino aún no existe, por lo que no se puede verificar el RBAC normal basado en la organización.

Si la solicitud tiene éxito, Capgo asignará automáticamente la misma clave API que org_super_admin tenía en la organización anterior.

Nota

org.create no se concede a las nuevas claves API por defecto. Actívalo Permitir crear organizaciones en el formulario de la clave API, o incluye "global_permissions": ["org.create"] al crear la clave mediante API.

Cuerpo de la solicitud

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

Ejemplo de solicitud

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/

Ejemplo de respuesta

{
  "id": "org_456"
}

Error de permisos

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

{
  "error": "permission_denied",
  "message": "Permission denied: org.create",
  "moreInfo": {}
}

PUT

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

Actualiza una organización existente. Requiere rol de admin en la organización de destino.

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/

Ejemplo de respuesta

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

ELIMINAR

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

Elimina una organización existente. Requiere permiso de eliminación en la organización de destino, normalmente a través del org_super_admin rol. Esta acción es irreversible y eliminará todas las apps, bundles (versiones) y recursos asociados.

El org.create el permiso global no permite eliminar organizaciones.

Parámetros de consulta

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

Ejemplo de solicitud

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

Ejemplo de respuesta

{
  "status": "ok"
}

Manejo de errores

Todos los errores utilizan el formato estándar descrito en la visión general de API.

Escenarios de error comunes y sus respuestas:

// Missing or invalid API key (HTTP 401)
{
  "error": "invalid_apikey",
  "message": "Invalid apikey",
  "moreInfo": {}
}

// The API key has no access to the requested organization
{
  "error": "invalid_org_id",
  "message": "You can't access this organization",
  "moreInfo": { "org_id": "046a36ac-e03c-4590-9257-bd6c9dba9ee8" }
}

// The organization requires API keys with an expiration date (HTTP 401)
{
  "error": "org_requires_expiring_key",
  "message": "This organization requires API keys with an expiration date. Please use a different key or update this key with an expiration date.",
  "moreInfo": {}
}

// Creating an organization without the org.create permission (HTTP 403)
{
  "error": "permission_denied",
  "message": "Permission denied: org.create",
  "moreInfo": {}
}

// max_apikey_expiration_days out of range on update
{
  "error": "invalid_max_expiration_days",
  "message": "Maximum expiration days must be between 1 and 365",
  "moreInfo": {}
}

Buenas prácticas

1. Nomenclatura: Usa nombres claros y descriptivos para las organizaciones
2. Roles: Asigna los roles adecuados a los miembros del equipo
3. Email: Usa un email de grupo para management_email y evita problemas si cambias tu email personal
4. Logo: Aloja los logos en un CDN fiable y usa URLs con HTTPS

Continuar desde Organizations

Si estás usando Organizaciones para planificar las operaciones del dashboard y de API, conéctalo con Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para el detalle de implementación en API Keys, Dispositivos para el detalle de implementación en Devices, y Bundles para el detalle de implementación en Bundles.