API de Organizaciones

Las organizaciones son la capa de multitenancy B2B en Auris. Una organización representa una empresa cliente dentro de tu tenant — con sus propios miembros, roles, configuración de SSO y verificación de dominio. Los usuarios pueden pertenecer a múltiples organizaciones con diferentes roles en cada una.

Roles de miembro de organización: OWNER (control total), ADMIN (gestionar miembros y configuración), MEMBER (acceso estándar), VIEWER (solo lectura).

Todos los endpoints requieren el encabezado x-tenant y el permiso manage:organizations salvo que se indique lo contrario.

CRUD de Organizaciones

GET/api/organizationsRequires: manage:organizations

Lista todas las organizaciones del tenant. Devuelve información resumida incluyendo el número de miembros y si hay alguna conexión SSO configurada.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20)
`search`	string	Buscar por nombre o nombre para mostrar de la organización

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "org_abc123",
        "name": "acme-corp",
        "displayName": "Acme Corporation",
        "memberCount": 45,
        "hasSso": true,
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 12, "totalPages": 1 }
  }
}

POST/api/organizationsRequires: manage:organizations

Crea una nueva organización. El campo name es un identificador legible por máquinas (minúsculas, se permiten guiones) que debe ser único dentro del tenant. El displayName es el nombre legible por humanos que se muestra en la UI.

Cuerpo de la solicitud


{
  "name": "acme-corp",
  "displayName": "Acme Corporation",
  "metadata": {
    "industry": "Manufacturing",
    "country": "US"
  }
}

displayName y metadata son opcionales.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "org_def456",
    "name": "acme-corp",
    "displayName": "Acme Corporation",
    "metadata": { "industry": "Manufacturing", "country": "US" },
    "memberCount": 0,
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`NAME_TAKEN`	409	Ya existe una organización con este nombre
`VALIDATION_ERROR`	400	Nombre de organización inválido (debe ser alfanumérico en minúsculas con guiones)

GET/api/organizations/[id]Requires: manage:organizations

Obtiene los detalles completos de una organización, incluyendo metadatos y estado del SSO.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "org_abc123",
    "name": "acme-corp",
    "displayName": "Acme Corporation",
    "metadata": { "industry": "Manufacturing" },
    "memberCount": 45,
    "hasSso": true,
    "ssoProvider": "saml",
    "verifiedDomains": ["acme-corp.com"],
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-02-01T12:00:00Z"
  }
}

PUT/api/organizations/[id]Requires: manage:organizations

Actualiza el nombre para mostrar o los metadatos de una organización. El campo name (identificador de máquina) no puede cambiarse después de la creación.

Cuerpo de la solicitud


{
  "displayName": "Acme Corp International",
  "metadata": {
    "industry": "Manufacturing",
    "country": "US",
    "tier": "enterprise"
  }
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "org_abc123",
    "displayName": "Acme Corp International",
    "metadata": { "industry": "Manufacturing", "country": "US", "tier": "enterprise" }
  }
}

DELETE/api/organizations/[id]Requires: manage:organizations

Elimina una organización. Todos los miembros son removidos de la organización. Las conexiones SSO y verificaciones de dominio son eliminadas. Las cuentas de usuario en sí no se eliminan.

Respuesta exitosa


{
  "ok": true,
  "data": { "deleted": true }
}

Gestión de Miembros

GET/api/organizations/[id]/membersRequires: manage:organizations

Lista todos los miembros de una organización con sus roles y fechas de incorporación.

Parámetros de consulta

Parámetro	Tipo	Descripción
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20)
`role`	`OWNER` \| `ADMIN` \| `MEMBER` \| `VIEWER`	Filtrar por rol

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "userId": "usr_abc123",
        "email": "[email protected]",
        "firstName": "Alice",
        "lastName": "Smith",
        "role": "ADMIN",
        "joinedAt": "2025-01-15T10:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 45, "totalPages": 3 }
  }
}

POST/api/organizations/[id]/membersRequires: manage:organizations

Agrega un usuario existente (por ID de usuario) a la organización con un rol especificado. Para agregar usuarios que aún no tienen cuenta, usa los endpoints de invitación.

Cuerpo de la solicitud


{
  "userId": "usr_abc123",
  "role": "MEMBER"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "role": "MEMBER",
    "joinedAt": "2025-02-18T11:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`USER_NOT_FOUND`	404	El usuario no existe en este tenant
`ALREADY_MEMBER`	409	El usuario ya es miembro de esta organización

PATCH/api/organizations/[id]/members/[userId]Requires: manage:organizations

Actualiza el rol de un miembro dentro de la organización. Solo se pueden cambiar los miembros con roles OWNER y ADMIN. Una organización siempre debe tener al menos un OWNER.

Cuerpo de la solicitud


{
  "role": "ADMIN"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "role": "ADMIN",
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`LAST_OWNER`	400	No se puede eliminar el último OWNER de una organización

DELETE/api/organizations/[id]/members/[userId]Requires: manage:organizations

Elimina un miembro de la organización. La cuenta del usuario no se elimina.

Respuesta exitosa


{
  "ok": true,
  "data": { "removed": true }
}

Invitaciones

GET/api/organizations/[id]/invitationsRequires: manage:organizations

Lista todas las invitaciones pendientes de una organización.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "inv_abc123",
        "email": "[email protected]",
        "role": "MEMBER",
        "status": "pending",
        "expiresAt": "2025-02-25T10:00:00Z",
        "createdAt": "2025-02-18T10:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
  }
}

Estados de invitación: pending, accepted, expired, cancelled.

POST/api/organizations/[id]/invitationsRequires: manage:organizations

Invita a un usuario a la organización por email. Se envía un email de invitación con un enlace de aceptación basado en token. Las invitaciones expiran después de 7 días. Si el email ya está asociado a un usuario del tenant, se le notifica directamente. Si no, se le pide que cree una cuenta primero.

Cuerpo de la solicitud


{
  "email": "[email protected]",
  "role": "MEMBER"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "inv_def456",
    "email": "[email protected]",
    "role": "MEMBER",
    "expiresAt": "2025-02-25T10:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`ALREADY_MEMBER`	409	El email ya es miembro activo de esta organización
`INVITATION_PENDING`	409	Ya existe una invitación pendiente para este email

DELETE/api/organizations/[id]/invitations/[invId]Requires: manage:organizations

Cancela una invitación pendiente. El enlace de invitación en el email queda inválido inmediatamente.

Respuesta exitosa


{
  "ok": true,
  "data": { "cancelled": true }
}

SSO Empresarial

El SSO (Single Sign-On) empresarial permite a los miembros de la organización autenticarse usando su proveedor de identidad (IdP) existente — ya sea SAML 2.0 o basado en OIDC. Las conexiones SSO están vinculadas a una organización y se activan automáticamente cuando los usuarios inician sesión con un email de dominio verificado.

Todos los endpoints de SSO requieren manage:sso_connections.

GET/api/organizations/[orgId]/sso/connectionsRequires: manage:sso_connections

Lista todas las conexiones SSO configuradas para una organización.

Respuesta exitosa


{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml",
      "domains": ["acme-corp.com"],
      "createdAt": "2025-01-20T09:00:00Z"
    }
  ]
}

Estados de conexión SSO: PENDING (configurado pero no activado), ACTIVE, DISABLED, ERROR.

POST/api/organizations/[orgId]/sso/connectionsRequires: manage:sso_connections

Crea una nueva conexión SSO. Para SAML, proporciona la URL de metadatos del IdP o el XML sin procesar. Para OIDC, proporciona la URL de descubrimiento y las credenciales del cliente.

Cuerpo de la solicitud — SAML


{
  "type": "saml",
  "name": "Acme Corporate IdP",
  "config": {
    "metadataUrl": "https://idp.acme-corp.com/metadata",
    "entityId": "https://idp.acme-corp.com",
    "ssoUrl": "https://idp.acme-corp.com/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\n..."
  }
}

Cuerpo de la solicitud — OIDC


{
  "type": "oidc",
  "name": "Acme OIDC",
  "config": {
    "discoveryUrl": "https://login.acme-corp.com/.well-known/openid-configuration",
    "clientId": "auris-sp-client",
    "clientSecret": "sp-client-secret"
  }
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "entityId": "https://api.altovar.net"
  }
}

El acsUrl (URL del Assertion Consumer Service) y el entityId son los valores que debes proporcionar al IdP durante la configuración del SP.

POST/api/organizations/[orgId]/sso/connections/[id]/activateRequires: manage:sso_connections

Activa una conexión SSO. Tras la activación, los usuarios con un email de dominio verificado son redirigidos automáticamente al proveedor SSO al iniciar sesión.

Solicitud: No se requiere cuerpo.

Respuesta exitosa


{
  "ok": true,
  "data": { "activated": true, "status": "ACTIVE" }
}

POST/api/organizations/[orgId]/sso/connections/[id]/deactivateRequires: manage:sso_connections

Desactiva una conexión SSO. Los usuarios con emails de dominio recurrirán a la autenticación estándar con contraseña hasta que el SSO sea reactivado.

Solicitud: No se requiere cuerpo.

Respuesta exitosa


{
  "ok": true,
  "data": { "deactivated": true, "status": "DISABLED" }
}

Verificación de Dominio

La verificación de dominio demuestra que controlas un dominio antes de habilitar la redirección automática basada en SSO para las direcciones de email de ese dominio. La verificación se realiza mediante un registro DNS TXT.

GET/api/organizations/[orgId]/sso/domainsRequires: manage:sso_connections

Lista todos los dominios asociados a la configuración SSO de una organización, incluyendo el estado de verificación.

Respuesta exitosa


{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-corp.com",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z"
    }
  ]
}

Estados de verificación de dominio: PENDING, VERIFYING, ACTIVE, FAILED.

POST/api/organizations/[orgId]/sso/domainsRequires: manage:sso_connections

Agrega un dominio e inicia la verificación. Se devuelve un verificationToken que debe añadirse como registro DNS TXT en el dominio. Luego llama al endpoint de verificación para confirmar.

Cuerpo de la solicitud


{
  "domain": "acme-corp.com"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "dom_def456",
    "domain": "acme-corp.com",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-ghi789jkl012",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-corp.com",
      "value": "auris-verify-ghi789jkl012"
    }
  }
}

Agrega el registro DNS TXT que aparece en dnsRecord en tu registrador de dominio, luego llama al endpoint de verificación.

POST/api/organizations/[orgId]/sso/domains/[id]/checkRequires: manage:sso_connections

Inicia la verificación DNS para un dominio. Auris realiza una consulta DNS TXT en vivo para buscar el token de verificación. Devuelve el nuevo estado inmediatamente.

Solicitud: No se requiere cuerpo.

Respuesta exitosa — verificado


{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "ACTIVE",
    "verifiedAt": "2025-02-18T15:00:00Z"
  }
}

Respuesta exitosa — aún no propagado


{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "PENDING",
    "message": "TXT record not found yet. DNS propagation can take up to 48 hours."
  }
}

La propagación DNS suele tardar minutos, pero en casos excepcionales puede tardar hasta 48 horas. Llama al endpoint de verificación periódicamente hasta que el estado pase a ACTIVE.

Relacionado

Multitenancy — Cómo las organizaciones se mapean a los tenants de Auris
Guía de Multitenancy B2B — Configura arquitectura multi-organización
SSO Empresarial — Configura SSO para miembros de la organización
Organizaciones — Gestiona organizaciones desde la Consola
API de SSO — Endpoints de conexiones SSO empresarial