> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiperai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear Usuario

> Create a new user account. Only accessible by administrators.


# Crear nuevo usuario

Crea una nueva cuenta de usuario. Solo accesible para administradores.

## Endpoint

```
POST /users
```

## Descripción

Este endpoint permite a los administradores crear nuevas cuentas de usuario en el sistema. Puede especificar varios atributos de usuario, incluidos rol, licencia y tipo de autenticación. Este es un endpoint administrativo que requiere permisos adecuados.

## Flujo de creación de usuarios

**Autentificación básica** (`authType: "basic"`): el usuario recibe un correo electrónico de bienvenida con un enlace de configuración de contraseña. La cuenta se crea sin verificar hasta que se establece la contraseña.

**SSO empresarial** (`authType: "enterprise"`): el usuario se crea verificado y puede iniciar sesión a través de SSO empresarial (Auth0, Microsoft AD, etc.). No se requiere configuración de contraseña.

## Autenticación

Requerido. Incluya su clave API en el encabezado de Autorización.

```bash theme={null}
Authorization: Bearer sk-your-api-key-here
```

## Solicitud

### Cuerpo de solicitud

| Parámetro        | Tipo     | Requerido | Predeterminado | Descripción                                                                                         |
| ---------------- | -------- | --------- | -------------- | --------------------------------------------------------------------------------------------------- |
| `name`           | cadena   | Sí        | -              | Nombre completo del usuario                                                                         |
| `username`       | cadena   | No        | -              | Nombre de usuario único (generado automáticamente desde el correo electrónico si no se proporciona) |
| `email`          | cadena   | Sí        | -              | Dirección de correo electrónico del usuario                                                         |
| `role`           | cadena   | No        | usuario        | Rol del usuario (admin, usuario, globalReader)                                                      |
| `license`        | cadena   | No        | Esencial       | Nivel de licencia de usuario (Essential, Growth, Ultra, Early Access)                               |
| `roleId`         | cadena   | No        | -              | ID de rol personalizado (MongoDB ObjectId)                                                          |
| `setupCompleted` | booleano | No        | falso          | Si se completó la configuración del usuario                                                         |
| `authType`       | cadena   | No        | básico         | Tipo de autenticación (básica, empresarial)                                                         |

### Solicitud de ejemplo

```bash theme={null}
curl -X POST "https://{customer.name}.hiperai.ai/api/external/users" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "role": "user",
    "license": "Growth",
    "setupCompleted": false,
    "authType": "enterprise"
  }'
```

## Respuesta

### Respuesta exitosa (201)

```json theme={null}
{
  "success": true,
  "message": "User created successfully",
  "user": {
    "id": "60a7c8f5e8b4f5001f7a8c23",
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "role": "user",
    "license": "Growth",
    "status": 1,
    "isVerified": false,
    "setupCompleted": false,
    "authType": "basic",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}
```

### Campos de respuesta

| Campo                 | Tipo     | Descripción                                 |
| --------------------- | -------- | ------------------------------------------- |
| `success`             | booleano | Siempre `true` para solicitudes exitosas    |
| `message`             | cadena   | Mensaje de éxito                            |
| `user`                | objeto   | Objeto de usuario creado                    |
| `user.id`             | cadena   | Identificador único del usuario             |
| `user.name`           | cadena   | Nombre completo del usuario                 |
| `user.username`       | cadena   | Nombre de usuario del usuario               |
| `user.email`          | cadena   | Dirección de correo electrónico del usuario |
| `user.role`           | cadena   | Rol del usuario                             |
| `user.license`        | cadena   | Nivel de licencia de usuario                |
| `user.status`         | entero   | Estado del usuario (1=activo)               |
| `user.isVerified`     | booleano | Si el usuario está verificado               |
| `user.setupCompleted` | booleano | Si se completó la configuración del usuario |
| `user.authType`       | cadena   | Tipo de autenticación                       |
| `user.createdAt`      | cadena   | Marca de tiempo de creación de usuario      |

## Ejemplo de uso

### JavaScript

```javascript theme={null}
const response = await fetch('https://{customer.name}.hiperai.ai/api/external/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    username: 'johndoe',
    email: 'john@example.com',
    role: 'user',
    license: 'Growth'
  })
});

const data = await response.json();

if (data.success) {
  console.log('User created:', data.user.name);
  console.log('User ID:', data.user.id);
}
```

### Pitón

```python theme={null}
import requests

headers = {
    'Authorization': 'Bearer sk-your-api-key-here',
    'Content-Type': 'application/json'
}

data = {
    'name': 'John Doe',
    'username': 'johndoe',
    'email': 'john@example.com',
    'role': 'user',
    'license': 'Growth'
}

response = requests.post('https://{customer.name}.hiperai.ai/api/external/users', 
                       headers=headers, json=data)
result = response.json()

if result['success']:
    print('User created:', result['user']['name'])
    print('User ID:', result['user']['id'])
```

### rizo

```bash theme={null}
curl -X POST "https://{customer.name}.hiperai.ai/api/external/users" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "role": "user",
    "license": "Growth"
  }'
```

## Respuestas de error

### 400 Solicitud incorrecta

```json theme={null}
{
  "success": false,
  "error": "Invalid request parameters",
  "message": "The 'name' field is required"
}
```

### 400 Tipo de autenticación no válido

```json theme={null}
{
  "success": false,
  "error": "Invalid authType",
  "message": "authType must be either \"basic\" or \"enterprise\""
}
```

### 400 campos obligatorios faltantes

```json theme={null}
{
  "success": false,
  "error": "Missing required fields",
  "message": "Name and email are required"
}
```

### 401 No autorizado

```json theme={null}
{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}
```

### 403 Prohibido

```json theme={null}
{
  "success": false,
  "error": "Access denied",
  "message": "Admin access required"
}
```

### 409 Conflicto

```json theme={null}
{
  "success": false,
  "error": "User already exists",
  "message": "A user with this email already exists"
}
```

## Validaciones y reglas de negocio

* **Valor de la licencia**: Debe ser una de las licencias permitidas (`Essential`, `Growth`, `Ultra`, `Early Access`). Los valores no válidos devuelven 400.
* **Capacidad de licencia**: Aplicada a través de `checkLicenseCapacity`. Si la capacidad está llena para el nivel seleccionado, devuelve 400.
* **Normalización del correo electrónico**: minúsculas y recortadas antes de la validación y el almacenamiento.
* **Normalización del nombre de usuario**: minúsculas y recortadas antes de la validación y el almacenamiento. Generado automáticamente desde el correo electrónico si no se proporciona.
* **Formato de correo electrónico**: validado con una expresión regular simple; los correos electrónicos no válidos devuelven 400.
* **Formato de nombre de usuario**: debe coincidir con `^[a-z0-9.-]{3,30}$`; Los nombres de usuario no válidos devuelven 400.
* **Singularidad**: `email`, `username` y `name` deben ser únicos. Los conflictos regresan 409.
* **Comportamiento de invitación por correo electrónico**: para la autenticación básica, los usuarios reciben correos electrónicos de bienvenida con enlaces de configuración de contraseña.

## Normalización y almacenamiento

* `email` y `username` siempre se guardan en minúsculas y recortados.

## Formas de error típicas

### 400 Licencia no válida

```json theme={null}
{
  "success": false,
  "error": "Invalid license",
  "message": "License must be one of: Essential, Growth, Ultra, Early Access"
}
```

### Licencia 400 no disponible

```json theme={null}
{
  "success": false,
  "error": "License unavailable",
  "message": "No Growth licenses available (used/limit)"
}
```

### 400 Correo electrónico no válido

```json theme={null}
{
  "success": false,
  "error": "Invalid email",
  "message": "Email format is invalid"
}
```

### 400 Nombre de usuario no válido

```json theme={null}
{
  "success": false,
  "error": "Invalid username",
  "message": "Username must be 3-30 chars, lowercase letters, digits, \".\", "-", or \"\""
}
```

### 409 Conflicto (singularidad)

```json theme={null}
{
  "success": false,
  "error": "Email/Username/Name already exists",
  "message": "A user with this email already exists"
}
```

## Roles de usuario

| Rol            | Descripción      | Permisos                                          |
| -------------- | ---------------- | ------------------------------------------------- |
| `admin`        | Administrador    | Acceso completo al sistema                        |
| `user`         | Usuario habitual | Acceso de usuario estándar                        |
| `globalReader` | Lector global    | Acceso al panel de administración de solo lectura |

## Niveles de licencia

| Licencia       | Descripción              | Características     |
| -------------- | ------------------------ | ------------------- |
| `Essential`    | Nivel básico             | Funciones limitadas |
| `Growth`       | Nivel profesional        | Funciones mejoradas |
| `Ultra`        | Nivel premium            | Funciones completas |
| `Early Access` | Nivel de acceso temprano | Funciones beta      |

## Tipos de autenticación

| Tipo         | Descripción                                                                                                            |
| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `basic`      | Autenticación de nombre de usuario/contraseña (el usuario recibe un correo electrónico de configuración de contraseña) |
| `enterprise` | Integración SSO empresarial (Auth0, Microsoft AD, etc.)                                                                |

## Casos de uso

* **Incorporación de usuarios**: cree nuevas cuentas de usuario para los miembros del equipo
* **Incorporación sin contraseña**: cree usuarios que reciban invitaciones por correo electrónico para establecer sus propias contraseñas.
* **Integración SSO**: cree usuarios que se autentiquen a través de proveedores de identidad externos
* **Creación masiva de usuarios**: crea múltiples usuarios mediante programación
* **Integración**: Crear usuarios desde sistemas externos
* **Tareas administrativas**: administrar cuentas de usuario a través de API

## Límites de tarifas

Este endpoint sigue los límites de velocidad estándar:

* 60 solicitudes por minuto
* 1000 solicitudes por hora


## OpenAPI

````yaml POST /users
openapi: 3.0.3
info:
  title: SecureAI External API
  description: >
    SecureAI External API provides AI chat completion and image generation
    capabilities with knowledge base retrieval, 

    security policies, and comprehensive usage tracking. This API is designed
    for external developers 

    and integrations using API key authentication.


    ## Key Features

    - **RAG (Retrieval-Augmented Generation)**: Automatically search knowledge
    bases for relevant context

    - **Multi-Model Support**: OpenAI, Anthropic, Google, Meta, and other AI
    models

    - **Model Redundancy & Failover**: Caller-defined failover chains (primary +
    fallbacks) with per-attempt timeouts

    - **OpenAI-Compatible Endpoint**: Point any OpenAI SDK at `/api/external/v1`
    — no code changes

    - **Image Generation**: Generate and edit images using Google Gemini 2.5
    Flash Image

    - **Speech-to-Speech (S2S)**: Real-time voice conversations using OpenAI
    Realtime API with WebRTC

    - **Security Policies**: SMLTP policy enforcement, per-call Prompt Shield,
    and signed compliance receipts

    - **Usage Tracking**: Comprehensive usage monitoring, self-service quota,
    and rate limiting

    - **Knowledge Base Integration**: Access to personal and shared knowledge
    bases

    - **User Management**: Complete user, group, and role management
    capabilities

    - **Audit Logging**: Comprehensive activity and security audit logs


    ## Authentication

    All endpoints (except health check) require API key authentication using
    Bearer token:

    ```

    Authorization: Bearer sk-your-api-key-here

    ```


    ## Billing and Usage

    By default, API requests are billed to the user account that owns the API
    key. You can specify 

    a different user to bill by including the `user_id` parameter in your
    request. This allows for:

    - Multi-tenant applications with per-user billing

    - Flexible completion limit management

    - Per-user "Usage by Model" settings


    ## Rate Limits

    - Default: 60 requests per minute, 1000 requests per hour

    - Daily limits: 100 requests (configurable)

    - Monthly limits: 10,000 requests (configurable)


    ## Base URL

    ```

    https://secureai.hiperai.ai/api/external

    ```
  version: 1.1.0
  contact:
    name: SecureAI Support
    email: support@secureai.hiperai.ai
  license:
    name: Proprietary
    url: https://secureai.hiperai.ai/terms
servers:
  - url: https://secureai.hiperai.ai/api/external
    description: Production server
  - url: http://localhost:3010/api/external
    description: Development server
security:
  - ApiKeyAuth: []
tags:
  - name: System
    description: System health and status endpoints
  - name: Discovery
    description: Endpoints to discover available models, indexes, and policies
  - name: Chat
    description: AI chat completion endpoints
  - name: User Management
    description: Endpoints for managing user accounts and roles
  - name: Index Management
    description: Endpoints for managing knowledge base indexes
  - name: Group Management
    description: Endpoints for managing user groups
  - name: SMLTP Security
    description: Endpoints for managing SMLTP security policies and audit logs
  - name: Role Management
    description: Endpoints for managing user roles
  - name: Activity Logs
    description: Endpoints for retrieving activity logs
externalDocs:
  description: SecureAI Documentation
  url: https://secureai.hiperai.ai/docs
paths:
  /users:
    post:
      tags:
        - User Management
      summary: Create New User
      description: |
        Create a new user account. Only accessible by administrators.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - username
                - email
                - password
              properties:
                name:
                  type: string
                  description: User's full name
                  example: John Doe
                username:
                  type: string
                  description: Unique username
                  example: johndoe
                email:
                  type: string
                  format: email
                  description: User's email address
                  example: john@example.com
                password:
                  type: string
                  description: User's password
                  example: securepassword123
                role:
                  type: string
                  enum:
                    - admin
                    - user
                    - globalReader
                  default: user
                  description: User's role
                  example: user
                license:
                  type: string
                  enum:
                    - Essential
                    - Growth
                    - Ultra
                    - Early Access
                  default: Essential
                  description: User's license tier
                  example: Growth
                roleId:
                  type: string
                  description: Custom role ID (MongoDB ObjectId)
                  example: 60a7c8f5e8b4f5001f7a8c24
                setupCompleted:
                  type: boolean
                  default: false
                  description: Whether user setup is completed
                  example: false
                authType:
                  type: string
                  enum:
                    - basic
                    - auth0
                  default: basic
                  description: Authentication type
                  example: basic
            example:
              name: John Doe
              username: johndoe
              email: john@example.com
              password: securepassword123
              role: user
              license: Growth
              setupCompleted: false
              authType: basic
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: User created successfully
                  user:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 60a7c8f5e8b4f5001f7a8c23
                      name:
                        type: string
                        example: John Doe
                      username:
                        type: string
                        example: johndoe
                      email:
                        type: string
                        example: john@example.com
                      role:
                        type: string
                        example: user
                      license:
                        type: string
                        example: Growth
                      status:
                        type: integer
                        example: 1
                      isVerified:
                        type: boolean
                        example: true
                      setupCompleted:
                        type: boolean
                        example: false
                      authType:
                        type: string
                        example: basic
                      createdAt:
                        type: string
                        format: date-time
                        example: '2024-01-15T10:30:00.000Z'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied - admin only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Invalid API key
        message:
          type: string
          example: The provided API key is invalid or has been revoked
        request_id:
          type: string
          example: req-abc123
          description: Request ID for tracking (if available)
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication using Bearer token format.
        Example: `Authorization: Bearer sk-your-api-key-here`

````