===========================
Endpoints de Cuentas
===========================

El módulo de cuentas expone una API REST bajo el prefijo ``/accounts/api/``
para la gestión de usuarios y claves SSH. Todos los endpoints requieren
autenticación. Las operaciones de listado, creación y eliminación de usuarios
están restringidas a administradores (superusuarios).

.. contents:: En esta página
   :local:
   :depth: 2

Usuarios — ``/accounts/api/users/``
=====================================

Gestión completa de usuarios del sistema. Los administradores pueden listar,
crear, actualizar y eliminar usuarios. Los usuarios regulares solo pueden
consultar y editar su propio perfil a través del endpoint ``/me/``.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/accounts/api/users/``
     - Listar usuarios (solo admin)
   * - ``POST``
     - ``/accounts/api/users/``
     - Crear nuevo usuario (solo admin)
   * - ``GET``
     - ``/accounts/api/users/{id}/``
     - Detalle de un usuario
   * - ``PUT``
     - ``/accounts/api/users/{id}/``
     - Actualizar usuario completo
   * - ``PATCH``
     - ``/accounts/api/users/{id}/``
     - Actualizar campos parciales
   * - ``DELETE``
     - ``/accounts/api/users/{id}/``
     - Eliminar usuario (solo admin)
   * - ``GET``
     - ``/accounts/api/users/me/``
     - Obtener perfil del usuario actual
   * - ``PATCH``
     - ``/accounts/api/users/me/``
     - Actualizar perfil del usuario actual

Permisos
--------

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Acción
     - Permiso requerido
   * - ``list``, ``create``, ``destroy``
     - Solo superusuarios
   * - ``retrieve``, ``update``, ``partial_update``
     - Superusuarios o el propio usuario
   * - ``me`` (GET/PATCH)
     - Cualquier usuario autenticado

**Ejemplo — Listar usuarios (admin):**

.. code-block:: bash

   curl -X GET https://panel.example.com/accounts/api/users/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta (lista):**

.. code-block:: json

   {
     "count": 15,
     "next": null,
     "previous": null,
     "results": [
       {
         "id": 1,
         "username": "admin",
         "email": "admin@example.com",
         "first_name": "Admin",
         "last_name": "NoxPanel",
         "role": "admin",
         "is_active": true,
         "is_verified": true,
         "is_superuser": true,
         "can_access_vps": true,
         "can_access_hosting": true,
         "can_access_billing": true,
         "can_access_ticketing": true,
         "company": "NoxPanel Inc.",
         "phone": "+34600000000",
         "created_at": "2026-01-01T00:00:00Z"
       }
     ]
   }

**Ejemplo — Obtener perfil propio:**

.. code-block:: bash

   curl -X GET https://panel.example.com/accounts/api/users/me/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta (perfil):**

.. code-block:: json

   {
     "id": 5,
     "username": "cliente1",
     "email": "cliente@example.com",
     "first_name": "Juan",
     "last_name": "Perez",
     "company": "Mi Empresa S.L.",
     "phone": "+34611222333",
     "role": "client",
     "is_verified": true,
     "can_access_vps": true,
     "can_access_hosting": true,
     "can_access_billing": true,
     "can_access_ticketing": true,
     "created_at": "2026-01-15T10:00:00Z"
   }

.. note::

   Los campos ``username``, ``role``, ``is_verified``, ``can_access_vps``,
   ``can_access_hosting``, ``can_access_billing`` y ``can_access_ticketing``
   son de solo lectura en el endpoint ``/me/``. Solo un administrador puede
   modificar estos campos a través del endpoint ``/users/{id}/``.

**Ejemplo — Actualizar perfil propio:**

.. code-block:: bash

   curl -X PATCH https://panel.example.com/accounts/api/users/me/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "first_name": "Juan Carlos",
       "phone": "+34699888777"
     }'

**Ejemplo — Detalle de usuario (admin):**

.. code-block:: bash

   curl -X GET https://panel.example.com/accounts/api/users/5/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta (detalle admin):**

.. code-block:: json

   {
     "id": 5,
     "username": "cliente1",
     "email": "cliente@example.com",
     "first_name": "Juan",
     "last_name": "Perez",
     "role": "client",
     "is_active": true,
     "is_verified": true,
     "is_superuser": false,
     "is_staff": false,
     "can_access_vps": true,
     "can_access_hosting": true,
     "can_access_billing": true,
     "can_access_ticketing": true,
     "company": "Mi Empresa S.L.",
     "phone": "+34611222333",
     "proxmox_username": "",
     "can_manage_vms": false,
     "vm_quota": 5,
     "created_at": "2026-01-15T10:00:00Z",
     "updated_at": "2026-02-01T14:30:00Z"
   }

Claves SSH — ``/accounts/api/ssh-keys/``
==========================================

Gestión de claves SSH del usuario autenticado. Cada usuario solo ve y gestiona
sus propias claves. Las claves se pueden utilizar para acceso a servidores y
shells del hosting.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/accounts/api/ssh-keys/``
     - Listar claves SSH del usuario
   * - ``POST``
     - ``/accounts/api/ssh-keys/``
     - Añadir nueva clave SSH
   * - ``GET``
     - ``/accounts/api/ssh-keys/{id}/``
     - Detalle de una clave
   * - ``PUT``
     - ``/accounts/api/ssh-keys/{id}/``
     - Actualizar clave completa
   * - ``PATCH``
     - ``/accounts/api/ssh-keys/{id}/``
     - Actualizar campos parciales
   * - ``DELETE``
     - ``/accounts/api/ssh-keys/{id}/``
     - Eliminar clave SSH

**Ejemplo — Listar claves SSH:**

.. code-block:: bash

   curl -X GET https://panel.example.com/accounts/api/ssh-keys/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta:**

.. code-block:: json

   {
     "count": 2,
     "next": null,
     "previous": null,
     "results": [
       {
         "id": 1,
         "name": "Portátil trabajo",
         "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG... usuario@portatil",
         "fingerprint": "SHA256:xR3bN7kQ2mP...",
         "key_type": "ssh-ed25519",
         "is_active": true,
         "last_used_at": "2026-02-08T15:30:00Z",
         "created_at": "2026-01-20T09:00:00Z"
       },
       {
         "id": 2,
         "name": "Servidor CI/CD",
         "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... deploy@ci",
         "fingerprint": "SHA256:aB4cD5eF6gH...",
         "key_type": "ssh-rsa",
         "is_active": true,
         "last_used_at": null,
         "created_at": "2026-02-01T12:00:00Z"
       }
     ]
   }

**Ejemplo — Añadir clave SSH:**

.. code-block:: bash

   curl -X POST https://panel.example.com/accounts/api/ssh-keys/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Mi nueva clave",
       "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINew... user@host"
     }'

**Respuesta (201 Created):**

.. code-block:: json

   {
     "id": 3,
     "name": "Mi nueva clave",
     "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINew... user@host",
     "fingerprint": "SHA256:nEw7kEy8fIn...",
     "key_type": "ssh-ed25519",
     "is_active": true,
     "last_used_at": null,
     "created_at": "2026-02-09T10:00:00Z"
   }

.. note::

   Los campos ``fingerprint``, ``key_type``, ``last_used_at`` y ``created_at``
   son de solo lectura y se generan automáticamente a partir de la clave pública
   proporcionada.

**Ejemplo — Eliminar clave SSH:**

.. code-block:: bash

   curl -X DELETE https://panel.example.com/accounts/api/ssh-keys/3/ \
     -H "Authorization: Bearer $TOKEN"

Devuelve ``204 No Content`` si la eliminación es exitosa.