Get All Roles

curl --request GET \
  --url https://secureai.hiperai.ai/api/external/roles \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://secureai.hiperai.ai/api/external/roles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "roles": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c26",
      "name": "custom_role",
      "displayName": "Custom Role",
      "description": "Custom role with specific permissions",
      "isSystem": false,
      "hasAdminPanelAccess": true,
      "permissions": [
        {
          "section": "user-management",
          "level": "admin"
        }
      ],
      "canInteractWithAI": true,
      "canUseChat": true,
      "userCount": 5,
      "createdBy": {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

GET

roles

Get All Roles

curl --request GET \
  --url https://secureai.hiperai.ai/api/external/roles \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://secureai.hiperai.ai/api/external/roles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "roles": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c26",
      "name": "custom_role",
      "displayName": "Custom Role",
      "description": "Custom role with specific permissions",
      "isSystem": false,
      "hasAdminPanelAccess": true,
      "permissions": [
        {
          "section": "user-management",
          "level": "admin"
        }
      ],
      "canInteractWithAI": true,
      "canUseChat": true,
      "userCount": 5,
      "createdBy": {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

Lista de roles

Recupere todos los roles de usuario disponibles en el sistema SecureAI.

Endpoint

GET /roles

Descripción

Este endpoint devuelve todos los roles de usuario disponibles en el sistema SecureAI. Proporciona información detallada sobre cada rol, incluidos permisos, descripciones y metadatos. Esto es útil para comprender los roles disponibles y sus capacidades.

Autenticación

Requerido: Clave API con privilegios de administrador

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

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`page`	entero	No	1	Número de página para paginación (predeterminado: 1)
`limit`	entero	No	20	Número de roles por página (predeterminado: 20)
`search`	cadena	No	-	Término de búsqueda para nombre, nombre para mostrar o descripción
`isSystem`	cadena	No	-	Filtrar por roles del sistema (verdadero/falso)
`sortBy`	cadena	No	creadoEn	Campo para ordenar por (predeterminado: “createdAt”)
`sortOrder`	cadena	No	desc	Orden de clasificación (asc/desc, predeterminado: “desc”)

Solicitud de ejemplo

GET /roles?page=1&limit=10&search=admin

Respuesta exitosa

Código de estado: 200 OK

{
  "success": true,
  "roles": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c26",
      "name": "custom_role",
      "displayName": "Custom Role",
      "description": "Custom role with specific permissions",
      "isSystem": false,
      "hasAdminPanelAccess": true,
      "permissions": [
        {
          "section": "user-management",
          "level": "admin"
        },
        {
          "section": "index-management",
          "level": "reader"
        }
      ],
      "canInteractWithAI": true,
      "canUseChat": true,
      "userCount": 5,
      "createdBy": {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

Campos de respuesta

Campo	Tipo	Descripción
`success`	booleano	Indica si la operación fue exitosa
`roles`	matriz	Matriz de objetos de rol
`roles[].id`	cadena	Identificador de rol único
`roles[].name`	cadena	Nombre del rol
`roles[].displayName`	cadena	Nombre para mostrar del rol
`roles[].description`	cadena	Descripción del rol
`roles[].isSystem`	booleano	Si se trata de una función del sistema
`roles[].hasAdminPanelAccess`	booleano	Si el rol tiene acceso al panel de administración
`roles[].permissions`	matriz	Matriz de objetos de permiso
`roles[].permissions[].section`	cadena	Sección de permisos
`roles[].permissions[].level`	cadena	Nivel de permiso
`roles[].canInteractWithAI`	booleano	Si el rol puede interactuar con la IA
`roles[].canUseChat`	booleano	Si el rol puede usar el chat
`roles[].userCount`	entero	Número de usuarios con este rol
`roles[].createdBy`	objeto	Usuario que creó el rol
`roles[].createdBy.id`	cadena	ID de usuario del creador
`roles[].createdBy.name`	cadena	Nombre del creador
`roles[].createdBy.email`	cadena	Correo electrónico del creador
`roles[].createdAt`	cadena	Marca de tiempo de creación
`roles[].updatedAt`	cadena	Marca de tiempo de la última actualización
`pagination`	objeto	Información de paginación
`pagination.page`	entero	Número de página actual
`pagination.limit`	entero	Artículos por página
`pagination.total`	entero	Número total de funciones
`pagination.pages`	entero	Número total de páginas

Ejemplo de uso

JavaScript

const listRoles = async (params = {}) => {
  const queryString = new URLSearchParams(params).toString();
  const url = `https://{customer.name}.hiperai.ai/api/external/roles${queryString ? `?${queryString}` : ''}`;
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk-your-api-key-here'
    }
  });
  
  return await response.json();
};

// Example usage
const result = await listRoles({
  page: 1,
  limit: 10,
  search: 'admin'
});
console.log(result.roles);

Pitón

import requests

def list_roles(params=None):
    url = "https://{customer.name}.hiperai.ai/api/external/roles"
    headers = {
        "Authorization": "Bearer sk-your-api-key-here"
    }
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Example usage
params = {
    "page": 1,
    "limit": 10,
    "search": "admin"
}

result = list_roles(params)
print(result["roles"])

rizo

curl -X GET "https://{customer.name}.hiperai.ai/api/external/roles?page=1&limit=10&search=admin" \
  -H "Authorization: Bearer sk-your-api-key-here"

Respuestas de error

401 No autorizado

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Prohibido

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Admin privileges required"
  }
}

429 Demasiadas solicitudes

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retryAfter": 60
  }
}

Casos de uso

Gestión de roles: enumera todos los roles disponibles para la asignación de usuarios
Revisión de permisos: comprenda qué permisos tiene cada rol
Control de acceso: planifique el acceso de los usuarios según los roles disponibles
Asignación de usuarios: asigne roles a los usuarios según sus necesidades
Análisis de roles: analiza el uso de roles y la distribución de usuarios

Límites de tarifas

Predeterminado: 100 solicitudes por minuto
Diario: 10.000 solicitudes por día
Mensual: 300.000 solicitudes por mes

Notas

Este endpoint requiere privilegios de administrador
Paginación basada en páginas: utiliza parámetros de página, no desplazamiento
Búsqueda: busca en los campos de nombre, nombre para mostrar y descripción.
Roles del sistema: puede filtrar por sistema o por roles personalizados
Clasificación: puede ordenar por cualquier campo en orden ascendente o descendente
Respuesta plana: la respuesta no está anidada en el objeto de datos
Conteo de usuarios: muestra cuántos usuarios tienen cada rol
Información del creador: muestra quién creó cada rol.

Autorizaciones

Authorization

string

header

requerido

API key authentication using Bearer token format. Example: Authorization: Bearer sk-your-api-key-here

Parámetros de consulta

page

integer

predeterminado:1

Page number for pagination

Rango requerido: x >= 1

limit

integer

predeterminado:20

Number of roles per page

Rango requerido: 1 <= x <= 100

string

Search term for role name, display name, or description

isSystem

enum<string>

Filter by system roles

Opciones disponibles:

true,

false

sortBy

string

predeterminado:createdAt

Field to sort by

sortOrder

enum<string>

predeterminado:desc

Sort order

Opciones disponibles:

asc,

desc

Respuesta

List of roles

success

boolean

Ejemplo:

true

roles

object[]

Show child attributes

pagination

object

Show child attributes

Primeros Pasos y Configuración

Modelos y Generación AI

Knowledge Base y RAG

Seguridad, Guardrails y Auditoría

Usuarios y Acceso (IAM)

Facturación, Cuotas y Webhooks

Listar Roles

Lista de roles

Endpoint

Descripción

Autenticación

Parámetros de consulta

Solicitud de ejemplo

Respuesta exitosa

Campos de respuesta

Ejemplo de uso

JavaScript

Pitón

rizo

Respuestas de error

401 No autorizado

403 Prohibido

429 Demasiadas solicitudes

Casos de uso

Límites de tarifas

Notas

Autorizaciones

Parámetros de consulta

Respuesta

​Lista de roles

​Endpoint

​Descripción

​Autenticación

​Parámetros de consulta

​Solicitud de ejemplo

​Respuesta exitosa

​Campos de respuesta

​Ejemplo de uso

​JavaScript

​Pitón

​rizo

​Respuestas de error

​401 No autorizado

​403 Prohibido

​429 Demasiadas solicitudes

​Casos de uso

​Límites de tarifas

​Notas

Autorizaciones

Parámetros de consulta

Respuesta

Lista de roles

Endpoint

Descripción

Autenticación

Parámetros de consulta

Solicitud de ejemplo

Respuesta exitosa

Campos de respuesta

Ejemplo de uso

JavaScript

Pitón

rizo

Respuestas de error

401 No autorizado

403 Prohibido

429 Demasiadas solicitudes

Casos de uso

Límites de tarifas

Notas